Next: 11. Licence Up: 10. Alphabetical listing of Previous: 10.1 A warning about Contents Index
model elimination rule
, 
, 
} model elimination rules
Each user function is presented within it's own subsection with the documentation broken into multiple parts: the synopsis, the default arguments, and the sections from the function's docstring.
The synopsis presents a brief description of the function. It is taken as the first line of the docstring when browsing the help system.
This section lists all the arguments taken by the function and their default values. To invoke the function type the function name then in brackets type a comma separated list of arguments.
The first argument printed is always `self' but you can safely ignore it. `self' is part of the object oriented programming within Python and is automatically prefixed to the list of arguments you supply. Therefore you can't provide `self' as the first argument even if you do try.
All other sections are created from the sectioning of the user function docstring.
Function for copying alignment tensor data.
tensor_from: The identification string of the alignment tensor to copy the data from.
pipe_from: The name of the data pipe to copy the alignment tensor data from.
tensor_to: The identification string of the alignment tensor to copy the data to.
pipe_to: The name of the data pipe to copy the alignment tensor data to.
This function will copy the alignment tensor data to a new tensor or a new data pipe. The destination data pipe must not contain any alignment tensor data corresponding to the tensor_to label. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe. Both the tensor_from and tensor_to arguments must be supplied.
To copy the alignment tensor data corresponding to `Pf1' from the data pipe `old' to the current data pipe, type one of:
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Pf1', `old')
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Pf1', pipe_from=
[0]
[0]`old')
To copy the alignment tensor data corresponding to `Otting' from the current data pipe to the data pipe new, type one of:
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Otting', pipe_to=
[0]
[0]`new')
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Otting', pipe_to=
[0]
[0]`new')
To copy the alignment tensor data of `Otting' to that of `Otting new', type one of:
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Otting', tensor_to=
[0]
[0]`Otting new')
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Pf1', tensor_to=
[0]
[0]`Otting new')
Function for deleting alignment tensor data.
tensor: The alignment tensor identification string.
This function will delete the specified alignment tensor data from the current data pipe.
Function for displaying the alignment tensor information.
tensor: The alignment tensor identification string.
Fix all alignment tensors so that they do not change during optimisation.
fixed: The flag specifying if the tensors should be fixed or variable.
Function for initialising the alignment tensor.
tensor: The alignment tensor identification string.
params: The alignment tensor data.
scale: The alignment tensor eigenvalue scaling value.
angle_units: The units for the angle parameters.
param_types: A flag to select different parameter combinations.
errors: A flag which determines if the alignment tensor data or its errors are being input.
Using this function, the alignment tensor data can be set up. The params argument should be a tuple of floating point numbers (a list surrounded by round brakets). These correspond to the parameters of the tensor, which can be specified by the param_types argument, where the values correspond to
Other formats may be added later. The relationship between the Saupe order matrix S and the alignment tensor A is
The probability matrix P is related to the alignment tensor A by
where I is the identity matrix. For the alignment tensor to be supplied in Hertz, the bond vectors must all be of equal length.
To set a rhombic tensor to the run `CaM', type one of:
relax> align_tensor.
[0]
[0]
[0]init(
[0]
[0]`super media', (
[0]
[0]-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=
[0]
[0]1)
relax> align_tensor.
[0]
[0]
[0]init(
[0]
[0]tensor=
[0]
[0]`super media', params=
[0]
[0](
[0]
[0]-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=
[0]
[0]1)
Function for calculating the 5D angles between all alignment tensors.
basis_set: The basis set to operate with.
tensors: A list of the tensors to apply the calculation to. If None, all tensors are used.
This function will calculate the angles between all loaded alignment tensors for the current data pipe. The matrices are first converted to a 5D vector form and then then angles are calculated. The angles are dependent on the basis set. If the basis_set argument is set to the default of 0, the vectors {Sxx, Syy, Sxy, Sxz, Syz} are used. If the basis_set argument is set to 1, the vectors {Szz, Sxxyy, Sxy, Sxz, Syz} are used instead.
Specify that one tensor is a reduction of another.
full_tensor: The full alignment tensor.
red_tensor: The reduce alignment tensor.
Prior to optimisation of the N-state model and Frame Order theories using alignment tensors, which tensor is a reduction of which other tensor must be specified through this user function.
To state that the alignment tensor loaded as `chi3 C-dom' is a reduction of `chi3 N-dom', type:
relax> align_tensor.
[0]
[0]reduction(
[0]
[0]full_tensor=
[0]
[0]`chi3 N-dom', red_tensor=
[0]
[0]`chi3 C-dom')
Set the domain label for the alignment tensor.
tensor: The alignment tensor to assign the domain label to.
domain: The domain label.
Prior to optimisation of the N-state model or Frame Order theories, the domain to which each alignment tensor belongs must be specified.
To link the alignment tensor loaded as `chi3 C-dom' to the C-terminal domain `C', type:
relax> align_tensor.
[0]
[0]set_domain(
[0]
[0]tensor=
[0]
[0]`chi3 C-dom', domain=
[0]
[0]`C')
Function for calculating the singular values for all tensors and the condition number.
basis_set: The basis set to operate with.
tensors: A list of the tensors to apply the calculation to. If None, all tensors are used.
This function will, using SVD, calculate the singular values of all tensors loaded for the current data pipe. If the basis_set argument is set to the default of 0, the matrix on which SVD will be performed is composed of the unitary basis set {Sxx, Syy, Sxy, Sxz, Syz} layed out as:
| Sxx1 Syy1 Sxy1 Sxz1 Syz1 |
| Sxx2 Syy2 Sxy2 Sxz2 Syz2 |
| Sxx3 Syy3 Sxy3 Sxz3 Syz3 |
| . . . . . |
| . . . . . |
| . . . . . |
| SxxN SyyN SxyN SxzN SyzN |
If basis_set is set to 1, the geometric basis set consisting of the stretching and skewing parameters Szz and Sxx-yy respectively {Szz, Sxxyy, Sxy, Sxz, Syz} will be used instead. The matrix is:
| Szz1 Sxxyy1 Sxy1 Sxz1 Syz1 |
| Szz2 Sxxyy2 Sxy2 Sxz2 Syz2 |
| Szz3 Sxxyy3 Sxy3 Sxz3 Syz3 |
| . . . . . |
| . . . . . |
| . . . . . |
| SzzN SxxyyN SxyN SxzN SyzN |
The relationships between the geometric and unitary basis sets are:
Szz = - Sxx - Syy,
Sxxyy = Sxx - Syy,
The SVD values and condition number are dependendent upon the basis set chosen.
Calculate the angles defining the XH bond vector within the diffusion frame.
If the diffusion tensor is isotropic, then nothing will be done.
If the diffusion tensor is axially symmetric, then the angle 
will be calculated for each XH bond vector.
If the diffusion tensor is asymmetric, then the three angles will be calculated.
Specify a citation to be added the BMRB data file.
cite_id: The citation ID string.
authors: The list of authors. Each author element is a list of four elements (the first name, last name, first initial, and middle initials).
doi: The DOI number, e.g. "10.1000/182".
pubmed_id: The identification code assigned to the publication by PubMed.
full_citation: The full citation as given in a reference list.
title: The title of the publication.
status: The publication status.
journal_abbrev: The standard journal abbreviation.
journal_full: The full journal name.
volume: The volume number.
issue: The issue number.
page_first: The first page number.
page_last: The last page number.
year: The publication year.
The full_citation should be in a format similar to that used in a journal article by either cutting and pasting from another document or by typing. Please include author names, title, journal, page numbers, and year or equivalent information for the type of publication given.
The journal status can only be one of:
The citation type can only be one of:
The standard journal abbreviation is that defined by the Chemical Abstract Services for the journal where the data are or will be published. If the data in the deposition are related to a J. Biomol. NMR paper, the value must be `J. Biomol. NMR' to alert the BMRB annotators so that the deposition is properly processed. If the depositor truly does not know the journal, a value of `not known' or `na' is acceptable.
To add the citation "d'Auvergne E. J., Gooley P.
. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494.", type:
relax> bmrb.
[0]
[0]
[0]citation(
[0]
[0]authors=
[0]
[0][["Edward", "d'Auvergne", "E.", "J."], ["Paul", "Gooley", "P.", "R."]], doi=
[0]
[0]"10.1039/b702202f", pubmed_id=
[0]
[0]"17579774", full_citation=
[0]
[0]"d'Auvergne E. J., Gooley P. R. (
[0]
[0]2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(
[0]
[0]7), 483-494.", title=
[0]
[0]"Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm.", status=
[0]
[0]"published", type=
[0]
[0]"journal", journal_abbrev=
[0]
[0]"Mol. Biosyst.", journal_full=
[0]
[0]"Molecular Biosystems", volume=
[0]
[0]3, issue=
[0]
[0]7, page_first=
[0]
[0]483, page_last=
[0]
[0]498, year=
[0]
[0]2007)
Display the BMRB data in NMR-STAR format.
Read BMRB files in the NMR-STAR format.
file: The name of the BMRB STAR formatted file.
dir: The directory where the file is located.
version: For the reading to use the given NMR-STAR version.
sample_conditions: The sample conditions label in the NMR-STAR file to restrict loading to.
To search for the results file in the current working directory, set dir to None. Note that only one sample condition can be read per relax data pipe. Therefore if sample_conditions is not given and multiple conditions exist in the NMR-STAR file, a RelaxError will be raised.
Specify the scripts used in the analysis.
dir: The directory name.
analysis_type: The type of analysis performed.
model_selection: The model selection technique used, if relevant.
engine: The software engine used in the analysis.
model_elim: A model-free specific flag specifying if model elimination was performed.
universal_solution: A model-free specific flag specifying if the universal solution was sought after.
This user function allows scripts used in the analysis to be included in the BMRB deposition. The following addition information may need to be specified with the script.
The analysis_type must be set. Allowable values include all the data pipe types used in relax, ie:
The model_selection argument only needs to be set if the script selects between different mathematical models. This can be anything, but the following are recommended:
The engine is the software used in the calculation, optimisation, etc. This can be anything, but those recognised by relax (automatic program info, citations, etc. added) include:
or R
values.
The model_elim flag is model-free specific and should be set if the methods from "d'Auvergne, E. J. and Gooley, P.
. (2006). Model-free model elimination: A new step in the model-free dynamic analysis of NMR relaxation data. J. Biomol. NMR, 35(2), 117-135." were used. This should be set to True for the full_analysis.py script.
The universal_solution flag is model-free specific and should be set if the methods from "d'Auvergne E. J., Gooley P.
. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494." were used. This should be set to True for the full_analysis.py script.
For BMRB deposition, to specify that the full_analysis.py script was used, type one of:
relax> bmrb.
[0]
[0]script(
[0]
[0]`full_analysis.
[0]
[0]py', `model-free', `AIC', `relax', True, True)
relax> bmrb.
[0]
[0]script(
[0]
[0]file=
[0]
[0]`full_analysis.
[0]
[0]py', dir=
[0]
[0]None, analysis_type=
[0]
[0]`model-free', model_selection=
[0]
[0]`AIC', engine=
[0]
[0]`relax', model_elim=
[0]
[0]True, universal_solution=
[0]
[0]True)
Specify the software used in the analysis.
name: The name of the software program utilised.
version: The version of the software, if applicable.
url: The web address of the software.
vendor_name: The name of the company or person behind the program.
cite_ids: A list of the citation ID numbers.
tasks: A list of all the tasks performed by the software.
This user function allows the software used in the analysis to be specified in full detail.
For the tasks list, this should be a python list of strings (eg. [`spectral processing']). Although not restricted to these, the values suggested by the BMRB are:
For BMRB deposition, to say that Sparky was used in the analysis, type:
relax> cite_id =
[0]
[0]bmrb.
[0]
[0]
[0]citation(
[0]
[0]authors=
[0]
[0][[`Tom', `Goddard', `T.', `D.'], [`D', `Kneller', `D.', `G.']], title=
[0]
[0]""Goddard, T. D. and Kneller, D. G., SPARKY 3, University of California, San Francisco."
relax> bmrb.
[0]
[0]software(
[0]
[0]`Sparky', version=
[0]
[0]`3.110', url=
[0]
[0]"http://www.
[0]
[0]
[0]cgl.
[0]
[0]ucsf.
[0]
[0]
[0]edu/home/sparky/", vendor_name=
[0]
[0]"Goddard, T. D.", cite_ids=
[0]
[0][cite_id], tasks=
[0]
[0]["spectral analysis"])
Select the software used in the analysis.
name: The name of the software program utilised.
version: The version of the software, if applicable.
Rather than specifying all the information directly, this user function allows the software packaged used in the analysis to be selected by name. The programs currently supported are:
More can be added if all relevant information (program name, description, website, original citation, purpose, etc.) is emailed to relax-users@gna.org.
Note that relax is automatically added to the BMRB file.
For BMRB deposition, to say that both NMRPipe and Sparky were used prior to relax, type:
relax> bmrb.
[0]
[0]software_select(
[0]
[0]`NMRPipe')
relax> bmrb.
[0]
[0]software_select(
[0]
[0]`Sparky', version=
[0]
[0]`3.113')
Select the thiol state of the system.
state: The thiol state.
The thiol state can be any text, thought the BMRB suggests the following:
Alternatively the pure states `reduced' or `oxidised' could be specified.
For BMRB deposition, to say that the protein studied is in the oxidised state, tyype one of:
relax> bmrb.
[0]
[0]thiol_state(
[0]
[0]`oxidised')
relax> bmrb.
[0]
[0]thiol_state(
[0]
[0]state=
[0]
[0]`oxidised')
Write the results to a BMRB NMR-STAR formatted file.
.sconsign.dblite
Function for calculating the function value.
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
Function for selecting which relaxation data to use in the consistency tests.
frq: The spectrometer frequency in Hz.
This function will select the relaxation data to use in the consistency tests corresponding to the given frequencies.
relax> consistency_tests.
[0]
[0]set_frq(
[0]
[0]600.0 * 1e6)
relax> consistency_tests.
[0]
[0]set_frq(
[0]
[0]frq=
[0]
[0]600.0 * 1e6)
Function for creating the Dasha script.
algor: The minimisation algorithm.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
The script file created is called `dir/dasha_script'.
The two minimisation algorithms within Dasha are accessible through the algor argument which can be set to:
For Levenberg-Marquardt minimisation, the function `lmin' will be called, while for Newton -Raphson, the function `min' will be executed.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
binary: The name of the executable Dasha program file.
$ dasha < dasha_script | tee dasha_results
If you would like to use a different Dasha executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path in front of the binary file name.
Function for extracting data from the Dasha results file.
dir: The directory where the file `dasha_results' is found.
Function for deselecting all spins.
To deselect all spins, simply type:
relax> deselect.
[0]
[0]
[0]all(
[0]
[0])
Function for deselecting the spins contained in a file.
file: The name of the file containing the list of spins to deselect.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
boolean: The boolean operator specifying how spins should be selected.
change_all: A flag specifying if all other spins should be changed.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
Empty lines and lines beginning with a hash are ignored.
The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified in the file to be selected.
To deselect all overlapped residues listed with residue numbers in the first column of the file `unresolved', type:
relax> deselect.
[0]
[0]read(
[0]
[0]`unresolved', res_num_col=
[0]
[0]1)
relax> deselect.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`unresolved', res_num_col=
[0]
[0]1)
To deselect the spins in the second column of the relaxation data file `r1.600' while selecting all other spins, for example type:
relax> deselect.
[0]
[0]read(
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
relax> deselect.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
Function for the reversal of the spin selection.
spin_id: The spin identification string.
By supplying the spin_id argument, a subset of spin can have their selection status reversed.
To deselect all currently selected spins and select those which are deselected type:
relax> deselect.
[0]
[0]reverse(
[0]
[0])
Function for deselecting specific spins.
spin_id: The spin identification string.
change_all: A flag specifying if all other spins should be changed.
The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified by `spin_id' to be selected.
To deselect all glycines and alanines, type:
relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:GLY|:ALA')
To deselect residue 12 MET type:
relax> deselect.
[0]
[0]spin(
[0]
[0]`:12')
relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:12')
relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:12&:MET')
Function for copying diffusion tensor data from one data pipe to another.
pipe_from: The name of the data pipe to copy the diffusion tensor data from.
pipe_to: The name of the data pipe to copy the diffusion tensor data to.
This function will copy the diffusion tensor data between data pipes. The destination data pipe must not contain any diffusion tensor data. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe (hence giving one argument is essential).
To copy the diffusion tensor from the data pipe `m1' to the current data pipe, type:
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]`m1')
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1')
To copy the diffusion tensor from the current data pipe to the data pipe `m9', type:
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m9')
To copy the diffusion tensor from the data pipe `m1' to `m2', type:
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')
Function for deleting diffusion tensor data.
This function will delete all diffusion tensor data from the current data pipe.
Function for displaying the diffusion tensor information.
Function for initialising the diffusion tensor.
params: The diffusion tensor data.
time_scale: The correlation time scaling value.
d_scale: The diffusion tensor eigenvalue scaling value.
angle_units: The units for the angle parameters.
param_types: A flag to select different parameter combinations.
spheroid_type: A string which, if supplied together with spheroid parameters, will restrict the tensor to either being `oblate' or `prolate'.
fixed: A flag specifying whether the diffusion tensor is fixed or can be optimised.
When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are equal,
=
=
. In this case, the orientation of the XH bond vector within the diffusion frame is inconsequential to relaxation, hence, the spherical or Euler angles are undefined. Therefore solely a single geometric parameter, either
or
, can fully and sufficiently parameterise the diffusion tensor. The correlation function for the global rotational diffusion is
1 - tau / tm
C(tau) = - e ,
5
To select isotropic diffusion, the parameters argument should be a single floating point number. The number is the value of the isotropic global correlation time,
, in seconds. To specify the time in nanoseconds, set the `time_scale' argument to 1e-9. Alternative parameters can be used by changing the `param_types' flag to the following integers
where
= 6
.
When two of the three eigenvalues of the diffusion tensor are equal, the molecule diffuses as a spheroid. Four pieces of information are required to specify this tensor, the two geometric parameters,
and
, and the two orientational parameters, the polar angle 
and the azimuthal angle 
describing the orientation of the axis of symmetry. The correlation function of the global diffusion is
_1_
1 \ - tau / tau_i
C(tau) = - > ci . e ,
5 /__
i=-1
where
^2 - 1)^2,
^2 (1 -
^2),
^2 - 1)^2,
and
-1 = 6
- 2
,
0 = 6
-
,
1 = 6
+ 2
.
The direction cosine
is defined as the cosine of the angle
between the XH bond vector and the unique axis of the diffusion tensor.
To select axially symmetric anisotropic diffusion, the parameters argument should be a tuple of floating point numbers of length four. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, `param_types', are
,
,
,
} (Default),
,
,
,
},
,
,
,
},
,
,
,
},
,
,
,
},
where
= 1 / 6
,
= 1/3 (
+ 2
),
=
-
,
=
/
.
The spherical angles {
,
} orienting the unique axis of the diffusion tensor within the PDB frame are defined between
,
2
,
while the angle
which is the angle between this axis and the given XH bond vector is defined between
2
.
The `spheroid_type' argument should be `oblate', `prolate', or None. The argument will be ignored if the diffusion tensor is not axially symmetric. If `oblate' is given, then the constraint
0 is used while if `prolate' is given, then the constraint
0 is used. If nothing is supplied, then
will be allowed to have any values. To prevent minimisation of diffusion tensor parameters in a space with two minima, it is recommended to specify which tensor is to be minimised, thereby partitioning the two minima into the two subspaces along the boundry
= 0.
When all three eigenvalues of the diffusion tensor are different, the molecule diffuses as an ellipsoid. This diffusion is also known as fully anisotropic, asymmetric, or rhombic. The full tensor is specified by six pieces of information, the three geometric parameters
,
, and
representing the isotropic, anisotropic, and rhombic components of the tensor, and the three Euler angles
, 
, and 
orienting the tensor within the PDB frame. The correlation function is
_2_
1 \ - tau / tau_i
C(tau) = - > ci . e ,
5 /__
i=-2
where the weights on the exponentials are
^2
^2,
^2
^2,
^2
^2,
Let
= sqrt(1 + 3
),
then
^4 +
^4 +
^4) - 1,
((1 + 3
)(
^4 + 2
^2
^2) + (1 - 3
)(
^4 + 2
^2
^2) - 2(
^4 + 2
^2
^2)).
-2 = 6
- 2
.
,
-1 = 6
-
(1 + 3
),
0 = 6
-
(1 - 3
),
1 = 6
+ 2
,
1 = 6
+ 2
.
.
The three direction cosines
,
, and
are the coordinates of a unit vector parallel to the XH bond vector. Hence the unit vector is [
,
,
].
To select fully anisotropic diffusion, the parameters argument should be a tuple of length six. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, `param_types', are
,
,
,
,
,
} (Default),
,
,
,
,
,
},
,
,
,
,
,
},
where
= 1 / 6
,
= 1/3 (
+
+
),
=
- (
+
)/2,
= (
-
)/2
.
The angles
,
, and
are the Euler angles describing the diffusion tensor within the PDB frame. These angles are defined using the z-y-z axis rotation notation where
is the initial rotation angle around the z-axis,
is the rotation angle around the y-axis, and
is the final rotation around the z-axis again. The angles are defined between
2
,
,
2
.
Within the PDB frame, the XH bond vector is described using the spherical angles
and
where
is the polar angle and
is the azimuthal angle defined between
,
2
.
When param_types is set to 3, then the elements of the diffusion tensor matrix defined within the PDB frame can be supplied.
The `time_scale' argument should be a floating point number. The only parameter affected by this value is
.
The `d_scale' argument should also be a floating point number. Parameters affected by this value are
,
,
,
,
,
, and
. Significantly,
is not affected.
The `angle_units' argument should either be the string `deg' or `rad'. Parameters affected are
,
,
,
, and
.
To set an isotropic diffusion tensor with a correlation time of 10 ns, type:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]10e-9)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0]10e-9)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]10.0, 1e-9)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0]10.0, time_scale=
[0]
[0]1e-9, fixed=
[0]
[0]True)
To select axially symmetric diffusion with a
value of 8.5 ns,
of 1.1,
value of 20 degrees, and
value of 20 degrees, type:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]8.5e-9, 1.1, 20.0, 20.0), param_types=
[0]
[0]2)
To select a spheroid diffusion tensor with a
value of 1.698e7,
value of 1.417e7,
value of 67.174 degrees, and
value of -83.718 degrees, type one of:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e7, 1.417e7, 67.174, -83.718), param_types=
[0]
[0]3)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e7, 1.417e7, 67.174, -83.718), param_types=
[0]
[0]3)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 67.174, -83.718), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 67.174, -83.718), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8, angle_units=
[0]
[0]`rad')
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8, angle_units=
[0]
[0]`rad', fixed=
[0]
[0]True)
To select ellipsoidal diffusion, type:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=
[0]
[0]2)
file: The file name prefix. For example if file is set to `temp', then the OpenDX program temp.net will be loaded.
dir: The directory to change to for running OpenDX. If this is set to None, OpenDX will be run in the current directory.
_exe: The OpenDX executable file.
vp_exec: A flag specifying whether to execute the visual program automatically at start-up. The default of True causes the program to be executed.
Function for creating a map of the given space in OpenDX format.
params: The parameters to be mapped. This argument should be an array of strings, the meanings of which are described below.
map_type: The type of map to create. For example the default, a 3D isosurface, the type is `Iso3D'. See below for more details.
spin_id: The spin identification numbe.
inc: The number of increments to map in each dimension. This value controls the resolution of the map.
lower: The lower bounds of the space. If you wish to change the lower bounds of the map then supply an array of length equal to the number of parameters in the model. A lower bound for each parameter must be supplied. If nothing is supplied then the defaults will be used.
upper: The upper bounds of the space. If you wish to change the upper bounds of the map then supply an array of length equal to the number of parameters in the model. A upper bound for each parameter must be supplied. If nothing is supplied then the defaults will be used.
axis_incs: The number of increments or ticks displaying parameter values along the axes of the OpenDX plot.
file_prefix: The file name. All the output files are prefixed with this name. The main file containing the data points will be called the value of `file'. The OpenDX program will be called `file.net' and the OpenDX import file will be called `file.general'.
dir: The directory to output files to. Set this to `None' if you do not want the files to be placed in subdirectory. If the directory does not exist, it will be created.
point: An array of parameter values where a point in the map, shown as a red sphere, will be placed. The length must be equal to the number of parameters.
point_file: The name of that the point output files will be prefixed with.
remap: A user supplied remapping function. This function will receive the parameter array and must return an array of equal length.
The map type can be changed by supplying the `map_type' keyword argument. Here is a list of currently supported map types:
(see table 10.1)
This argument is case insensitive.
The following commands will generate a map of the extended model-free space for model `m5' consisting of the parameters {
, 
,
}. Files will be output into the directory `dx' and will be prefixed by `map'. In this case, the system is a protein and residue number 6 will be mapped.
relax> dx.
[0]
[0]map(
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6')
relax> dx.
[0]
[0]map(
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6', file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')
relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6', inc=
[0]
[0]20, file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')
relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6', map_type=
[0]
[0]`Iso3D', inc=
[0]
[0]20, file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')
To map the model-free space `m4' for residue 2, spin N6 defined by the parameters {
,
, 
}, name the results `test', and to place the files in the current directory, use one of the following commands:
relax> dx.
[0]
[0]map(
[0]
[0][`S2', `te', `Rex'], spin_id=
[0]
[0]`:2@N6', file_prefix=
[0]
[0]`test', dir=
[0]
[0]None)
relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`S2', `te', `Rex'], spin_id=
[0]
[0]`:2@N6', inc=
[0]
[0]100, file_prefix=
[0]
[0]`test', dir=
[0]
[0]None)
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.2)
(see table 10.3)
Function for model elimination.
function: A user supplied function for model elimination.
args: A tuple of arguments for model elimination.
This function is used for model validation to eliminate or reject models prior to model selection. Model validation is a part of mathematical modelling whereby models are either accepted or rejected.
Empirical rules are used for model rejection and are listed below. However these can be overridden by supplying a function. The function should accept five arguments, a string defining a certain parameter, the value of the parameter, the minimisation instance (ie the residue index if the model is residue specific), and the function arguments. If the model is rejected, the function should return True, otherwise it should return False. The function will be executed multiple times, once for each parameter of the model.
The `args' keyword argument should be a tuple, a list enclosed in round brackets, and will be passed to the user supplied function or the inbuilt function. For a description of the arguments accepted by the inbuilt functions, see below.
Once a model is rejected, the select flag corresponding to that model will be set to False so that model selection, or any other function, will then skip the model.
model elimination rule
The local
, in some cases, may exceed the value expected for a global correlation time. Generally the
value will be stuck at the upper limit defined for the parameter. These models are eliminated using the rule:
c
The default value of c is 50 ns, although this can be overridden by supplying the value (in seconds) as the first element of the args tuple.
,
,
} model elimination rules
These parameters may experience the same problem as the local
in that the model fails and the parameter value is stuck at the upper limit. These parameters are constrained using the formula (
,
,
2
). These failed models are eliminated using the rule:
,
,
c .
The default value of c is 1.5. Because of round-off errors and the constraint algorithm, setting c to 2 will result in no models being eliminated as the minimised parameters will always be less than 2
. The value can be changed by supplying the value as the second element of the tuple.
The `args' argument must be a tuple of length 2, the elements of which must be numbers. For example, to eliminate models which have a local
value greater than 25 ns and models with internal correlation times greater than 1.5 times
, set `args' to (25 * 1e-9, 1.5).
Function for either fixing or allowing parameter values to change during optimisation.
element: Which element to fix.
fixed: A flag specifying if the parameters should be fixed or allowed to change.
The keyword argument `element' can be any of the following:
`diff' - the diffusion tensor parameters. This will allow all diffusion tensor parameters to be toggled.
`all_spins' - using this keyword, all parameters from all spins will be toggled.
`all' - all parameter will be toggled. This is equivalent to combining both `diff' and `all_spins'.
The flag `fixed', if set to True, will fix parameters during optimisation whereas a value of False will allow parameters to vary.
Create a PDB file representing the Frame Order cone models.
size: The size of the geometric object in Å.
inc: The number of increments used to create the geometric object.
file: The name of the PDB file to create.
dir: The directory where the file is to be located.
force: A flag which, if set to True, will overwrite the any pre-existing file.
This function creates a PDB file containing an artificial geometric structure representing the Frame Order cone models.
There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue `PIV'. The cone consists of numerous H atoms of the residue `CON'. The cone axis vector is presented as the residue `AXE' with one carbon atom positioned at the pivot and the other 
Åaway on the cone axis (set by the size argument). Finally, if Monte Carlo have been performed, there will be multiple `MCC' residues representing the cone for each simulation, and multiple `MCA' residues representing the multiple cone axes.
To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined by the cone axis. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.
Match the domains to PDB files.
domain: The domain to associate the PDB file to.
pdb: The PDB file to associate the domain to.
To display the frame order cone models within Pymol, the two domains need to be associated with PDB files. Then the reference domain will be fixed in the PDB frame, and the moving domain will be rotated to its average position.
To set the `N' domain to the PDB file `bax_N_1J7O_1
.pdb', type one of:
relax> frame_order.
[0]
[0]
[0]domain_to_pdb(
[0]
[0]`N', `bax_N_1J7O_1st.
[0]
[0]pdb')
relax> frame_order.
[0]
[0]
[0]domain_to_pdb(
[0]
[0]domain=
[0]
[0]`N', pdb=
[0]
[0]`bax_N_1J7O_1st.
[0]
[0]pdb')
Set the pivot point for the two body motion in the structural coordinate system.
pivot: The pivot point for the motion (e.g. the position between the 2 domains in PDB coordinates).
To set the pivot point, type one of:
relax> frame_order.
[0]
[0]pivot(
[0]
[0][12.067, 14.313, -3.2675])
relax> frame_order.
[0]
[0]pivot(
[0]
[0]pivot=
[0]
[0][12.067, 14.313, -3.2675])
Set the reference domain for the `2-domain' Frame Order theories.
ref: The domain which will act as the frame of reference. This is only valid for the `2-domain' Frame Order theories.
Prior to optimisation of the `2-domain' Frame Order theories, which of the two domains will act as the frame of reference must be specified. This is important for the attachment of cones to domains, etc.
To set up the isotropic cone frame order model with `centre' domain being the frame of reference, type:
relax> frame_order.
[0]
[0]ref_domain(
[0]
[0]ref=
[0]
[0]`centre')
Select and set up the Frame Order model.
model: The name of the preset Frame Order model.
Prior to optimisation, the Frame Order model should be selected. These models consist of three parameter categories:
and y-axes are defined as the
and y-axes of the eigenframe.
rank order parameter.
The list of available models are:
Euler angle ave_pos_alpha is dropped from the model. The symmetry also collapses the eigenframe to a single z-axis defined by the parameters axis_theta and axis_phi.
To select the isotropic cone model, type:
relax> frame_order.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`iso cone')
Set the spectrometer frequency of the experiment.
id: The experiment identification string.
frq: The spectrometer frequency in Hertz.
This user function allows the spectrometer frequency of a given experiment to be set.
file: The name of the file.
dir: The directory name.
grace_exe: The Grace executable file.
This function can be used to execute Grace to view the specified file the Grace `.agr' file and the execute Grace. If the directory name is set to None, the file will be assumed to be in the current working directory.
To view the file `s2.agr' in the directory `grace', type:
relax> grace.
[0]
[0]view(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]view(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]
[0]agr', dir=
[0]
[0]`grace')
Function for creating a grace `.agr' file.
x_data_type: The data type for the X-axis (no regular expression is allowed).
_data_type: The data type for the Y-axis (no regular expression is allowed).
spin_id: The spin identification string.
plot_data: The data to use for the plot.
norm: Flag for the normalisation of series type data.
file: The name of the file.
dir: The directory name.
force: A flag which, if set to True, will cause the file to be overwritten.
This function is designed to be as flexible as possible so that any combination of data can be plotted. The output is in the format of a Grace plot (also known as ACE/gr, Xmgr, and xmgrace) which only supports two dimensional plots. Three types of keyword arguments can be used to create various types of plot. These include the X-axis and Y-axis data types, the spin identification string, and an argument for selecting what to actually plot.
The X-axis and Y-axis data type arguments should be plain strings, regular expression is not allowed. If the X-axis data type argument is not given, the plot will default to having the spin sequence along the x-axis. The two axes of the Grace plot can be absolutely any of the data types listed in the tables below. The only limitation, currently anyway, is that the data must belong to the same data pipe.
The spin identification string can be used to limit which spins are used in the plot. The default is that all spins will be used, however, these arguments can be used to select a subset of all spins, or a single spin for plots of Monte Carlo simulations, etc.
The property which is actually plotted can be controlled by the `plot_data' argument. It can be one of the following:
Normalisation is only allowed for series type data, for example the R
exponential curves, and will be ignored for all other data types. If the norm flag is set to True then the y-value of the first point of the series will be set to 1. This normalisation is useful for highlighting errors in the data sets.
To write the NOE values for all spins to the Grace file `noe.agr', type one of:
relax> grace.
[0]
[0]write(
[0]
[0]`spin', `noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`spin', y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr', force=
[0]
[0]True)
To create a Grace file of `S2' vs. `te' for all spins, type one of:
relax> grace.
[0]
[0]write(
[0]
[0]`S2', `te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`S2', y_data_type=
[0]
[0]`te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`S2', y_data_type=
[0]
[0]`te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr', force=
[0]
[0]True)
To create a Grace file of the Monte Carlo simulation values of `Rex' vs. `te' for residue 123, type one of:
relax> grace.
[0]
[0]write(
[0]
[0]`Rex', `te', spin_id=
[0]
[0]`:123', plot_data=
[0]
[0]`sims', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`Rex', y_data_type=
[0]
[0]`te', spin_id=
[0]
[0]`:123', plot_data=
[0]
[0]`sims', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
By plotting the peak intensities, the integrity of exponential relaxation curves can be checked and anomalies searched for prior to model-free analysis or reduced spectral density mapping. For example the normalised average peak intensities can be plotted verses the relaxation time periods for the relaxation curves of all residues of a protein. The normalisation, whereby the initial peak intensity of each residue I(0) is set to 1, emphasises any problems. To produce this Grace file, type:
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`relax_times', y_data_type=
[0]
[0]`ave_int', file=
[0]
[0]`intensities_norm.
[0]
[0]
[0]agr', force=
[0]
[0]True, norm=
[0]
[0]True)
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.4)
(see table 10.5)
(see table 10.6)
(see table 10.7)
(see table 10.8)
The grid search function.
lower: An array of the lower bound parameter values for the grid search. The length of the array should be equal to the number of parameters in the model.
upper: An array of the upper bound parameter values for the grid search. The length of the array should be equal to the number of parameters in the model.
inc: The number of increments to search over. If a single integer is given then the number of increments will be equal in all dimensions. Different numbers of increments in each direction can be set if `inc' is set to an array of integers of length equal to the number of parameters.
constraints: A boolean flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
Turn the function introductions off.
Turn the function introductions on.
Function for selecting which relaxation data to use in the 
mapping.
frq: The spectrometer frequency in Hz.
This function will select the relaxation data to use in the reduced spectral density mapping corresponding to the given frequency.
relax> jw_mapping.
[0]
[0]set_frq(
[0]
[0]600.0 * 1e6)
relax> jw_mapping.
[0]
[0]set_frq(
[0]
[0]frq=
[0]
[0]600.0 * 1e6)
The arguments, which should all be strings, specify the minimiser as well as its options. A minimum of one argument is required. As this calls the minfx function `generic_minimise' the full list of allowed arguments is shown below in the reproduced `generic_minimise' docstring. Ignore all sections except those labelled as minimisation algorithms and minimisation options. Also do not select the Method of Multipliers constraint algorithm as this is used in combination with the given minimisation algorithm if the keyword argument `constraints' is set to 1. The grid search algorithm should also not be selected as this is accessed using the `grid' function instead. The first argument passed will be set to the minimisation algorithm while all other arguments will be set to the minimisation options.
Keyword arguments differ from normal arguments having the form `keyword = value'. All arguments must precede keyword arguments in python. For more information see the examples section below or the python tutorial.
func_tol: The function tolerance. This is used to terminate minimisation once the function value between iterations is less than the tolerance. The default value is 1e-25.
grad_tol: The gradient tolerance. Minimisation is terminated if the current gradient value is less than the tolerance. The default value is None.
max_iterations: The maximum number of iterations. The default value is 1e7.
constraints: A boolean flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).
scaling: The diagonal scaling boolean flag. The default that scaling is on (scaling=True).
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
Diagonal scaling is the transformation of parameter values such that each value has a similar order of magnitude. Certain minimisation techniques, for example the trust region methods, perform extremely poorly with badly scaled problems. In addition, methods which are insensitive to scaling such as Newton minimisation may still benefit due to the minimisation of round off errors.
In Model-free analysis for example, if
= 0.5,
= 200 ps, and
= 15 1/s at 600 MHz, the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18].
is divided by (2 *
* 600,000,000)**2 to make it field strength independent. The scaling vector for this model may be something like [1.0, 1e-9, 1/(2 *
* 6e8)**2]. By dividing the unscaled parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0]. To revert to the original unscaled parameter vector, the scaled parameter vector and scaling vector are multiplied.
To apply Newton minimisation together with the GMW81 Hessian modification algorithm, the More and Thuente line search algorithm, a function tolerance of 1e-25, no gradient tolerance, a maximum of 10,000,000 iterations, constraints turned on to limit parameter values, and have normal printout, type any combination of:
relax> minimise(
[0]
[0]`newton')
relax> minimise(
[0]
[0]`Newton')
relax> minimise(
[0]
[0]`newton', `gmw')
relax> minimise(
[0]
[0]`newton', `mt')
relax> minimise(
[0]
[0]`newton', `gmw', `mt')
relax> minimise(
[0]
[0]`newton', `mt', `gmw')
relax> minimise(
[0]
[0]`newton', func_tol=
[0]
[0]1e-25)
relax> minimise(
[0]
[0]`newton', func_tol=
[0]
[0]1e-25, grad_tol=
[0]
[0]None)
relax> minimise(
[0]
[0]`newton', max_iter=
[0]
[0]1e7)
relax> minimise(
[0]
[0]`newton', constraints=
[0]
[0]True, max_iter=
[0]
[0]1e7)
relax> minimise(
[0]
[0]`newton', verbosity=
[0]
[0]1)
To use constrained Simplex minimisation with a maximum of 5000 iterations, type:
relax> minimise(
[0]
[0]`simplex', constraints=
[0]
[0]True, max_iter=
[0]
[0]5000)
All the text which follows is a reproduction of the docstring of the generic_minimise function from the minfx python package. Only take note of the minimisation algorithms and minimisation options sections, the other sections are not relevant for this function. The Grid search and Method of Multipliers algorithms CANNOT be selected as minimisation algorithms for this function.
The section entitled Keyword Arguments is also completely inaccessible therefore please ignore that text.
Generic minimisation function.
This is a generic function which can be used to access all minimisers using the same set of function arguments. These are the function tolerance value for convergence tests, the maximum number of iterations, a flag specifying which data structures should be returned, and a flag specifying the amount of detail to print to screen.
func: The function which returns the value.
dfunc: The function which returns the gradient.
d2func: The function which returns the Hessian.
args: The tuple of arguments to supply to the functions func, dfunc, and d2func.
x0: The vector of initial parameter value estimates (as an array).
min_algor: A string specifying which minimisation technique to use.
min_options: A tuple to pass to the minimisation function as the min_options keyword.
func_tol: The function tolerance value. Once the function value between iterations decreases below this value, minimisation is terminated.
grad_tol: The gradient tolerance value.
maxiter: The maximum number of iterations.
A: Linear constraint matrix m*n (A.x
).
: Linear constraint scalar vector (A.x
).
: Lower bound constraint vector (
).
: Upper bound constraint vector (
).
c: User supplied constraint function.
dc: User supplied constraint gradient function.
d2c: User supplied constraint Hessian function.
full_output: A flag specifying which data structures should be returned.
print_flag: A flag specifying how much information should be printed to standard output during minimisation. 0 means no output, 1 means minimal output, and values above 1 increase the amount of output printed.
The following values of the `full_output' flag will return, in tuple form, the following data
, f_count, g_count, h_count, warning)',
where the data names correspond to
A minimisation function is selected if the minimisation algorithm argument, which should be a string, matches a certain pattern. Because the python regular expression `match' statement is used, various strings can be supplied to select the same minimisation algorithm. Below is a list of the minimisation algorithms available together with the corresponding patterns.
This is a short description of python regular expression, for more information, see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
To select a minimisation algorithm, set the argument to a string which matches the given pattern.
Unconstrained line search methods:
(see table 10.9)
Unconstrained trust-region methods:
(see table 10.10)
Unconstrained conjugate gradient methods:
(see table 10.11)
Miscellaneous unconstrained methods:
(see table 10.12)
Constrained methods:
(see table 10.13)
The minimisation options can be given in any order.
Line search algorithms. These are used in the line search methods and the conjugate gradient methods. The default is the Backtracking line search.
(see table 10.14)
Hessian modifications. These are used in the Newton, Dogleg, and Exact trust region algorithms.
(see table 10.15)
Hessian type, these are used in a few of the trust region methods including the Dogleg and Exact trust region algorithms. In these cases, when the Hessian type is set to Newton, a Hessian modification can also be supplied as above. The default Hessian type is Newton, and the default Hessian modification when Newton is selected is the GMW algorithm.
(see table 10.16)
For Newton minimisation, the default line search algorithm is the More and Thuente line search, while the default Hessian modification is the GMW algorithm.
Function to create a model-free model.
model: The name of the model-free model.
equation: The model-free equation.
params: The array of parameter names of the model.
spin_id: The spin identification string.
`mf_orig' selects the original model-free equations with parameters {
,
}. `mf_ext' selects the extended model-free equations with parameters {
,
,
,
}. `mf_ext2' selects the extended model-free equations with parameters {
,
, 
,
}.
The following parameters are accepted for the original model-free equation:
The following parameters are accepted for the extended model-free equation:
=
*
.
The following parameters are accepted for the extended 2 model-free equation:
The following parameters are accepted for all equations:
.
If `spin_id' is supplied then the model will only be created for the corresponding spins. Otherwise the model will be created for all spins.
The following commands will create the model-free model `m1' which is based on the original model-free equation and contains the single parameter `S2'.
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]`m1', `mf_orig', [`S2'])
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]model=
[0]
[0]`m1', params=
[0]
[0][`S2'], equation=
[0]
[0]`mf_orig')
The following commands will create the model-free model `large_model' which is based on the extended model-free equation and contains the seven parameters `S2f', `tf', `S2', `ts', `Rex', `CSA', `r'.
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]`large_model', `mf_ext', [`S2f', `tf', `S2', `ts', `Rex', `CSA', `r'])
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]model=
[0]
[0]`large_model', params=
[0]
[0][`S2f', `tf', `S2', `ts', `Rex', `CSA', `r'], equation=
[0]
[0]`mf_ext')
Function for deleting all model-free data from the current data pipe.
To delete all model-free data, type:
relax> model_free.
[0]
[0]
[0]delete(
[0]
[0])
Function for removing the local
parameter from a model.
spin_id: The spin identification string.
This function will remove the local
parameter from the model-free parameter set. If there is no local
parameter within the set nothing will happen.
If no spin identification string is given, then the function will apply to all spins.
The following command will remove the parameter `tm':
relax> model_free.
[0]
[0]remove_tm(
[0]
[0])
Function for the selection of a preset model-free model.
model: The name of the preset model.
The standard preset model-free models are
,
},
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
The preset model-free models with optimisation of the CSA value are
},
,
},
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
}.
The preset model-free models with optimisation of the bond length are
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
,
,
,
,
},
,
,
,
,
,
},
, CSA,
}.
The preset model-free models with both optimisation of the bond length and CSA are
, CSA},
, CSA,
},
, CSA,
,
},
, CSA,
,
},
, CSA,
,
,
},
, CSA,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
,
},
, CSA,
}.
Warning: The models in the thirties range fail when using standard R
, R
, and NOE relaxation data. This is due to the extreme flexibly of these models where a change in the parameter `r' is compensated by a corresponding change in the parameter `CSA' and vice versa.
Additional preset model-free models, which are simply extensions of the above models with the addition of a local
parameter are:
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
,
,
,
,
},
,
,
,
,
,
},
,
}.
The preset model-free models with optimisation of the CSA value are
, CSA},
, CSA,
},
, CSA,
,
},
, CSA,
,
},
, CSA,
,
,
},
, CSA,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
,
},
, CSA,
}.
The preset model-free models with optimisation of the bond length are
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
,
,
,
,
},
,
,
,
,
,
},
,
,
,
,
,
},
,
,
,
,
,
,
},
,
, CSA,
}.
The preset model-free models with both optimisation of the bond length and CSA are
,
, CSA},
,
, CSA,
},
,
, CSA,
,
},
,
, CSA,
,
},
,
, CSA,
,
,
},
,
, CSA,
,
,
},
,
, CSA,
,
,
,
},
,
, CSA,
,
,
,
},
,
, CSA,
,
,
,
,
},
,
, CSA,
}.
If `spin_id' is supplied then the model will only be selected for the corresponding spins. Otherwise the model will be selected for all spins.
To pick model `m1' for all selected spins, type:
relax> model_free.
[0]
[0]select_model(
[0]
[0]`m1')
relax> model_free.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`m1')
Function for model selection.
method: The model selection technique (see below).
modsel_pipe: The name of the new data pipe which will be created by this user function by the copying of the selected data pipe.
pipes: An array containing the names of all data pipes to include in model selection.
The following model selection methods are supported:
For the methods `Bootstrap', `Expect', and `Overall', the function `monte_carlo' should have previously been executed with the type argument set to the appropriate value to modify its behaviour.
If the pipes argument is not supplied then all data pipes will be used for model selection.
For model-free analysis, if the preset models 1 to 5 are minimised and loaded into the program, the following commands will carry out AIC model selection and to place the selected results into the `mixed' data pipe, type one of:
relax> model_selection(
[0]
[0]`AIC', `mixed')
relax> model_selection(
[0]
[0]method=
[0]
[0]`AIC', modsel_pipe=
[0]
[0]`mixed')
relax> model_selection(
[0]
[0]`AIC', `mixed', [`m1', `m2', `m3', `m4', `m5'])
relax> model_selection(
[0]
[0]method=
[0]
[0]`AIC', modsel_pipe=
[0]
[0]`mixed', pipes=
[0]
[0][`m1', `m2', `m3', `m4', `m5'])
Function for copying all data associated with a molecule.
pipe_from: The data pipe containing the molecule from which the data will be copied. This defaults to the current data pipe.
mol_from: The molecule identifier string of the molecule to copy the data from.
pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.
mol_to: The molecule identifier string of the molecule to copy the data to.
This function will copy all the data associated with a molecule to a second molecule. This includes residue and spin system information. The new molecule must not yet exist.
To copy the molecule data from the molecule `GST' to the new molecule `wt-GST', type:
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]`#GST', `#wt-GST')
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]mol_from=
[0]
[0]`#GST', mol_to=
[0]
[0]`#wt-GST')
To copy the molecule data of the molecule `Ap4Aase' from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]mol_from=
[0]
[0]`#ApAase', pipe_to=
[0]
[0]`m2')
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', mol_from=
[0]
[0]`#ApAase', pipe_to=
[0]
[0]`m2', mol_to=
[0]
[0]`#ApAase')
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for creating a new molecule.
mol_name: The name of the molecule.
This function will add a new molecule data container to the relax data storage object. The same molecule name cannot be used more than once. The molecule type need not be specified. However if it given, it should be one of `protein', `RNA', `DNA', `organic molecule', `inorganic molecule', `other'.
To create the molecules `Ap4Aase', `ATP', and `MgF4', type:
relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`Ap4Aase')
relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`ATP')
relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`MgF4')
Function for deleting molecules.
mol_id: The molecule identifier string.
This function can be used to delete a single or sets of molecules.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for displaying the molecule information.
mol_id: The molecule identifier string.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for naming a molecule.
mol_id: The molecule identification string corresponding to one or more molecules.
force: A flag which if True will cause the molecule to be renamed.
This function simply allows molecules to be named (or renamed).
To rename the molecule `Ap4Aase' to `Inhib Ap4Aase', type one of:
relax> molecule.
[0]
[0]name(
[0]
[0]`#Ap4Aase', `Inhib Ap4Aase', True)
relax> molecule.
[0]
[0]name(
[0]
[0]mol_id=
[0]
[0]`#Ap4Aase', name=
[0]
[0]`Inhib Ap4Aase', force=
[0]
[0]True)
This assumes the molecule `Ap4Aase' already exists.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
mol_id: The molecule identification string corresponding to one or more molecules.
force: A flag which if True will cause the molecule to type to be overwritten.
This function allows the type of the molecule to be specified. It can be one of:
To set the molecule `Ap4Aase' to the `polypeptide(L)' type, type one of:
relax> molecule.
[0]
[0]type(
[0]
[0]`#Ap4Aase', `polypeptide(
[0]
[0]L)', True)
relax> molecule.
[0]
[0]type(
[0]
[0]mol_id=
[0]
[0]`#Ap4Aase', type=
[0]
[0]`polypeptide(
[0]
[0]L)', force=
[0]
[0]True)
Function for clearing the Molmol command history.
Function for executing a user supplied Molmol command.
command: The Molmol command to execute.
This user function allows you to pass Molmol commands to the program. This can be useful for automation or scripting.
To reinitialise the Molmol instance:
relax> molmol.
[0]
[0]
[0]command(
[0]
[0]"InitAll yes")
Function for executing Molmol macros.
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
This function allows residues specific values to be mapped to a structure through Molmol macros. Currently only the `classic' style, which is described below, is available.
The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.
To map the order parameter values,
, onto the structure using the classic style, type:
relax> molmol.
[0]
[0]macro_exec(
[0]
[0]`S2')
relax> molmol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2')
relax> molmol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic")
Apply the Molmol ribbon style.
This function applies the Molmol ribbon style which is equivalent to clicking on `ribbon' in the Molmol side menu. To do this, the following commands are executed:
To apply the ribbon style to the PDB file loaded, type:
relax> molmol.
[0]
[0]ribbon(
[0]
[0])
Function displaying the diffusion tensor PDB geometric object over the loaded PDB.
file: The name of the PDB file containing the tensor geometric object.
In executing this user function, a PDB file must have previously been loaded , a geometric object or polygon representing the Brownian rotational diffusion tensor will be overlain with the loaded PDB file and displayed within Molmol. The PDB file containing the geometric object must be created using the complementary `pdb.create_diff_tensor_pdb()' user function.
To display the diffusion tensor, the multiple commands will be executed. To overlay the structure with the diffusion tensor, everything will be selected and reoriented and moved to their original PDB frame positions:
Next the tensor PDB file is read in, selected, and the covalent bonds of the PDB CONECT records calculated:
Then only the atoms and bonds of the geometric object are selected and the `ball/stick' style applied:
The appearance is finally touched up:
Function for viewing the collection of molecules extracted from the PDB file.
relax> molmol.
[0]
[0]view(
[0]
[0])
relax> molmol.
[0]
[0]view(
[0]
[0])
Function for creating Molmol macros.
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
file: The name of the file.
dir: The directory name.
force: A flag which, if set to True, will cause the file to be overwritten.
This function allows residues specific values to be mapped to a structure through the creation of a Molmol `*.mac' macro which can be executed in Molmol by clicking on `File, Macro, Execute User...'. Currently only the `classic' style, which is described below, is available.
The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.
To create a Molmol macro mapping the order parameter values,
, onto the structure using the classic style, type:
relax> molmol.
[0]
[0]write(
[0]
[0]`S2')
relax> molmol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2')
relax> molmol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic", file=
[0]
[0]`s2.
[0]
[0]mac', dir=
[0]
[0]`molmol')
Creator: Edward d'Auvergne
Argument string: "classic"
Description: The classic style draws the backbone of a protein in the Molmol `neon' style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.
Supported data types:
(see table 10.17)
The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.
(see table 10.18)
The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.
(see table 10.19)
Function for creating simulation data.
method: The simulation method.
The method argument can either be set to `back_calc' or `direct', the choice of which determines the simulation type. If the values or parameters are calculated rather than minimised, this option will have no effect, hence, `back_calc' and `direct' are identical.
For error analysis, the method argument should be set to `back_calc' which will result in proper Monte Carlo simulations. The data used for each simulation is back calculated from the minimised model parameters and is randomised using Gaussian noise where the standard deviation is from the original error set. When the method is set to `back_calc', this function should only be called after the model is fully minimised.
The simulation type can be changed by setting the method argument to `direct'. This will result in simulations which cannot be used in error analysis and which are no longer Monte Carlo simulations. However, these simulations are required for certain model selection techniques (see the documentation for the model selection function for details), and can be used for other purposes. Rather than the data being back calculated from the fitted model parameters, the data is generated by taking the original data and randomising using Gaussian noise with the standard deviations set to the original error set.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations, 
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for calculating parameter errors from the Monte Carlo simulations.
prune: Legacy argument corresponding to `trim' in Art Palmer's Modelfree program.
Parameter errors are calculated as the standard deviation of the distribution of parameter values. This function should never be used if parameter values are obtained by minimisation and the simulation data are generated using the method `direct'. The reason is because only true Monte Carlo simulations can give the true parameter errors.
The prune argument is legacy code which corresponds to the `trim' option in Art Palmer's Modelfree program. To remove failed simulations, the eliminate function should be used prior to this function. Eliminating the simulations specifically identifies and removes the failed simulations whereas the prune argument will only, in a few cases, positively identify failed simulations but only if severe parameter limits have been imposed. Most failed models will pass through the pruning process and hence cause a catastrophic increase in the parameter errors. If the argument must be used, the following must be taken into account. If the values or parameters are calculated rather than minimised, the prune argument must be set to zero. The value of this argument is proportional to the number of simulations removed prior to error calculation. If prune is set to 0.0, all simulations are used for calculating errors, whereas a value of 1.0 excludes all data. In almost all cases prune must be set to zero, any value greater than zero will result in an underestimation of the error values. If a value is supplied, the lower and upper tails of the distribution of chi-squared values will be excluded from the error calculation.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for setting the initial simulation parameter values.
This function only effects where minimisation occurs and can therefore be skipped if the values or parameters are calculated rather than minimised. However, if accidentally run in this case, the results will be unaffected. It should only be called after the model or run is fully minimised. Once called, the functions `grid_search' and `minimise' will only effect the simulations and not the model parameters.
The initial values of the parameters for each simulation is set to the minimised parameters of the model. A grid search can be undertaken for each simulation instead, although this is computationally expensive and unnecessary. The minimisation function should be executed for a second time after running this function.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for turning simulations off.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for turning simulations on.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for setting up Monte Carlo simulations.
number: The number of Monte Carlo simulations.
This function must be called prior to any of the other Monte Carlo functions. The effect is that the number of simulations will be set and that simulations will be turned on.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Centre of mass (CoM) analysis.
pivot_point: The pivot point of the motions between the two domains.
centre: The optional argument for manually specifying the CoM of the initial position prior to the N rotations to the positions of the N states.
This function is used for analysing the domain motion information content of the N states from the N-state model. The states do not correspond to physical states, hence nothing can be extracted from the individual states. This analysis involves the calculation of the pivot to centre of mass (pivot-CoM) order parameter and subsequent cone of motions.
For the analysis, both the pivot point and centre of mass must be specified. The supplied pivot point must be a vector of floating point numbers of length 3. If the centre keyword argument is supplied, it must also be a vector of floating point numbers (of length 3). If the centre argument is not supplied, then the CoM will be calulcated from the selected parts of a previously loaded structure.
To perform an analysis where the pivot is at the origin and the CoM is set to the N-terminal domain of a previously loaded PDB file (the C-terminal domain has been deselected), type:
relax> n_state_model.
[0]
[0]CoM(
[0]
[0])
To perform an analysis where the pivot is at the origin (because the real pivot has been shifted to this position) and the CoM is at the position [0, 0, 1], type one of:
relax> n_state_model.
[0]
[0]CoM(
[0]
[0]centre=
[0]
[0][0, 0, 1])
relax> n_state_model.
[0]
[0]CoM(
[0]
[0]centre=
[0]
[0][0.0, 0.0, 1.0])
relax> n_state_model.
[0]
[0]CoM(
[0]
[0]pivot_point=
[0]
[0][0.0, 0.0, 0.0], centre=
[0]
[0][0.0, 0.0, 1.0])
Create a PDB file representing the cone models from the centre of mass (CoM) analysis.
cone_type: The type of cone model to represent.
scale: Value for scaling the pivot-CoM distance which the size of the cone defaults to.
file: The name of the PDB file.
dir: The directory where the file is located.
force: A flag which, if set to True, will overwrite the any pre-existing file.
This function creates a PDB file containing an artificial geometric structure to represent the various cone models. These models include:
The model can be selected by setting the cone_type argument to one of these strings. The cone is represented as an isotropic cone with its axis parallel to the average pivot-CoM vector, the vertex placed at the pivot point of the domain motions, and the length of the edge of the cone equal to the pivot-CoM distance multipled by the scaling argument. The resultant PDB file can subsequently read into any molecular viewer.
There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue `PIV'. The cone consists of numerous H atoms of the residue `CON'. The average pivot-CoM vector is presented as the residue `AVE' with one carbon atom positioned at the pivot and the other at the head of the vector (after scaling by the scale argument). Finally, if Monte Carlo have been performed, there will be multiple `MCC' residues representing the cone for each simulation, and multiple `MCA' residues representing the varying average pivot-CoM vector for each simulation.
To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined from the average pivot-CoM vector. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.
Eliminate the structures or states with no probability.
Simply type:
relax> n_state_model.
[0]
[0]
[0]elim_no_prob(
[0]
[0]N=
[0]
[0]8)
Set the number of states in the N-state model.
N: The number of states.
Prior to optimisation, the number of states in the N-state model can be specified. If the number of states is not set, then this parameter will be equal to the number of loaded structures.
To set up an 8-state model, type:
relax> n_state_model.
[0]
[0]number_of_states(
[0]
[0]N=
[0]
[0]8)
Set the reference domain for the `2-domain' N-state model.
ref: The domain which will act as the frame of reference. This is only valid for the `2-domain' N-state model.
Prior to optimisation of the `2-domain' N-state model, which of the two domains will act as the frame of reference must be specified. The N-states will be rotations of the other domain, so to switch the frame of reference to the other domain simply transpose the rotation matrices.
To set up a 5-state model with `C' domain being the frame of reference, type:
relax> n_state_model.
[0]
[0]ref_domain(
[0]
[0]ref=
[0]
[0]`C')
Select the N-state model type and set up the model.
model: The name of the preset N-state model.
Prior to optimisation, the N-state model type should be selected. The preset models are:
`2-domain' - The N-state model for a system of two domains, where one domain experiences a a reduced tensor.
`population' - The N-state model whereby only populations are optimised. The structures loaded into relax are assumed to be fixed. I.e. if two domains are present, the Euler angles for each state are fixed. The parameters of the model include the weight or probability for each state and the alignment tensor - {p0, p1, ..., pN, Axx, Ayy, Axy, Axz, Ayz}.
`fixed' - The N-state model whereby all motions are fixed and all populations are fixed to the set probabilities. The parameters of the model are simply the alignment tensor, {Axx, Ayy, Axy, Axz, Ayz}.
To analyse populations of states, type:
relax> n_state_model.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`populations')
Read NOESY or ROESY restraints from a file.
file: The name of the file containing the relaxation data.
dir: The directory where the file is located.
proton1_col: The column containing the first proton of the NOE or ROE cross peak.
proton2_col: The column containing the second proton of the NOE or ROE cross peak.
lower_col: The column containing the lower NOE bound.
upper_col: The column containing the upper NOE bound.
sep: The column separator (the default is white space).
This function can automatically determine the format of the file, for example Xplor formatted restraint files. A generically formatted file is also supported if it contains minimally four columns with the two proton names and the upper and lower bounds, as specified by the *_col arguments. The proton names need to be in the spin identification string format.
To read the Xplor formatted restraint file `NOE.xpl', type one of:
relax> noe.
[0]
[0]read_restraints(
[0]
[0]`NOE.
[0]
[0]xpl')
relax> noe.
[0]
[0]read_restraints(
[0]
[0]file=
[0]
[0]`NOE.
[0]
[0]xpl')
To read the generic formatted file `noes', type one of:
relax> noe.
[0]
[0]read_restraints(
[0]
[0]file=
[0]
[0]`NOE.
[0]
[0]xpl', proton1_col=
[0]
[0]0, proton2_col=
[0]
[0]1, lower_col=
[0]
[0]2, upper_col=
[0]
[0]3)
Set the steady-state NOE spectrum type for pre-loaded peak intensities.
spectrum_type: The type of steady-state NOE spectrum, one of `ref' or `sat'.
spectrum_id: The spectrum identification string.
The spectrum_type argument can have the following values:
Peak intensities should be loaded before calling this user function via the `spectrum.read_intensities()' user function. The intensity values will then be associated with a spectrum identifier which can be used here.
Function for creating the Modelfree4 input files.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
binary: The name of the executable Modelfree program file.
diff_search: See the Modelfree4 manual for `diffusion_search'.
sims: The number of Monte Carlo simulations.
sim_type: See the Modelfree4 manual.
trim: See the Modelfree4 manual.
steps: See the Modelfree4 manual.
constraints: A flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).
heteronuc_type: A three letter string describing the heteronucleus type, ie 15N, 13C, etc.
atom1: The symbol of the X heteronucleus in the pdb file.
atom2: The symbol of the H nucleus in the pdb file.
spin_id: The spin identification string.
The following files are created
The file `dir/run.sh' contains the single command,
`modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out',
which can be used to execute modelfree4.
If you would like to use a different Modelfree executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path infront of the binary file name.
Function for executing Modelfree4.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
binary: The name of the executable Modelfree program file.
Modelfree 4 will be executed as
$ modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out
If a PDB file is loaded and non-isotropic diffusion is selected, then the file name will be placed on the command line as `-s pdb_file_name'.
If you would like to use a different Modelfree executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path in front of the binary file name.
Function for extracting data from the Modelfree4 `mfout' star formatted file.
dir: The directory where the file `mfout' is found.
Specify which atom is the paramagnetic centre.
pos: The atomic position.
atom_id: The atom ID string.
pipe: The data pipe containing the structures to extract the centre from.
verbosity: The amount of information to print out.
fix: A flag specifying if the paramagnetic centre should be fixed during optimisation.
ave_pos: A flag specifying if the position of the atom is to be averaged across all models.
force: A flag which if True will cause the current paramagnetic centre to be overwritten.
This function is required for specifying where the paramagnetic centre is located in the loaded structure file. If no structure number is given, then the average atom position will be calculated if multiple structures are loaded.
A different set of structures than those loaded into the current data pipe can also be used to determine the position, or its average. This can be achieved by loading the alternative structures into another data pipe, and then specifying that pipe through the pipe argument.
If the ave_pos flag is set to True, the average position from all models will be used as the position of the paramagnetic centre. If False, then the positions from all structures will be used. If multiple positions are used, then a fast paramagnetic centre motion will be assumed so that PCSs for a single tensor will be calculated for each position, and the PCS values linearly averaged.
If the paramagnetic centre is the lanthanide Dysprosium which is labelled as
in a loaded PDB file, then type one of:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]`Dy')
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]atom_id=
[0]
[0]`Dy')
If the carbon atom `C1' of residue `4' in the PDB file is to be used as the paramagnetic centre, then type:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]`:4@C1')
To state that the Dy3+ atomic position is [0.136, 12.543, 4.356], type one of:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0][0.136, 12.543, 4.356])
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]pos=
[0]
[0][0.136, 12.543, 4.356])
To find an unknown paramagnetic centre, type:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]fix=
[0]
[0]False)
Back calculate the pseudo-contact shifts.
align_id: The alignment ID string.
Calculate the PCS Q-factor for the selected spins.
spin_id: The spin ID string for restricting to subset of all selected spins.
For this function to work, the back-calculated PCS data must first be generated by the analysis specific code. Otherwise a warning will be given.
To calculate the PCS Q-factor for only the spins `@H26', `@H27', and `@H28', type one of:
relax> pcs.
[0]
[0]
[0]calc_q_factors(
[0]
[0]`@H26 & @H27 & @H28')
relax> pcs.
[0]
[0]
[0]calc_q_factors(
[0]
[0]spin_id=
[0]
[0]`@H26 & @H27 & @H28')
Copy PCS data from pipe_from to pipe_to.
pipe_from: The name of the pipe to copy the PCS data from.
pipe_to: The name of the pipe to copy the PCS data to.
align_id: The alignment ID string.
This function will copy PCS data from `pipe_from' to `pipe_to'. If align_id is not given then all PCS data will be copied, otherwise only a specific data set will be.
To copy all PCS data from pipe `m1' to pipe `m9', type one of:
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', align_id=
[0]
[0]None)
To copy only the `Th' PCS data from `m3' to `m6', type one of:
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `Th')
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', align_id=
[0]
[0]`Th')
Generate a correlation plot of the measured vs. the back-calculated PCSs.
format: The format of the plot data.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
Two formats are currently supported. If format is set to `grace', then a Grace plot file will be created. If the format arg is set to None, then a plain text list of the measured and back-calculated data will be created.
To create a Grace plot of the data, type:
relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0])
To create a plain text list of the measured and back-calculated data, type one of:
relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0]None)
relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0]format=
[0]
[0]None)
Delete the PCS data corresponding to the alignment ID.
align_id: The alignment ID string.
To delete the PCS data corresponding to align_id=`PH_gel', type:
relax> pcs.
[0]
[0]
[0]delete(
[0]
[0]`PH_gel')
Display the PCS data corresponding to the alignment ID.
align_id: The alignment ID string.
To display the `phage' PCS data, type:
relax> pcs.
[0]
[0]
[0]display(
[0]
[0]`phage')
align_id: The alignment ID string.
file: The name of the file containing the PCS data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The PCS data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The following commands will read the PCS data out of the file `Tb.txt' where the columns are separated by the symbol `,', and store the PCSs under the ID `Tb'.
relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', sep=
[0]
[0]`,')
To read the 15N and 1H PCSs from the file `Eu.txt', where the 15N values are in the 4
column and the 1H in the 9
, type both the following:
relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@N', res_num_col=
[0]
[0]1, data_col=
[0]
[0]4)
relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@H', res_num_col=
[0]
[0]1, data_col=
[0]
[0]9)
Set optimisation weights on the PCS data.
align_id: The alignment ID string.
spin_id: The spin ID string.
weight: The weighting value.
This function can be used to force the PCS to contribute more or less to the chi-squared optimisation statistic. The higher the value, the more importance the PCS will have.
align_id: The alignment ID string.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory. The `align_id' argument are required for selecting which PCS data set will be written to file.
Read the Bruker Protein Dynamics Centre (PDC) file.
ri_id: The relaxation data ID string.
file: The name of the PDC file.
dir: The directory where the file is located.
This user function is used to load all of the data out of a Bruker PDC file for subsequent analysis within relax.
Function for copying a data pipe.
pipe_from: The name of the source data pipe to copy the data from.
pipe_to: The name of the target data pipe to copy the data to.
This user function allows the contents of a data pipe to be copied. If the `pipe_from' keyword argument is set to None the current data pipe is assumed. The data pipe corresponding to `pipe_to' must not yet exist.
To copy the contents of the `m1' data pipe to the `m2' data pipe, type:
relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')
relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')
If the current data pipe is `m1', then the following command can be used:
relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m2')
Function for initialising a data pipe.
pipe_name: The name of the data pipe.
pipe_type: The type of data pipe.
The data pipe name can be any string however the data pipe type can only be one of the following:
To set up a model-free analysis data pipe with the name `m5', type:
relax> pipe.
[0]
[0]
[0]create(
[0]
[0]`m5', `mf')
Print the name of the current pipe.
To run the user function, type:
relax> pipe.
[0]
[0]
[0]current(
[0]
[0])
Function for deleting a data pipe.
pipe_name: The name of the data pipe.
This function will permanently remove the data pipe and all of its contents. If the pipe name is not given, then all data pipes will be deleted.
Print a list of all the data pipes.
To run the user function, type:
relax> pipe.
[0]
[0]
[0]display(
[0]
[0])
Create a hybrid data pipe by fusing a number of other data pipes.
hybrid: The name of the hybrid data pipe to create.
pipes: An array containing the names of all data pipes to hybridise.
This user function can be used to construct hybrid models. An example of the use of a hybrid model could be if the protein consists of two independent domains. These two domains could be analysed separately, each having their own optimised diffusion tensors. The N-terminal domain data pipe could be called `N_sphere' while the C-terminal domain could be called `C_ellipsoid'. These two data pipes could then be hybridised into a single data pipe called `mixed model' by typing:
relax> pipe.
[0]
[0]
[0]hybridise(
[0]
[0]`mixed model', [`N_sphere', `C_ellipsoid'])
relax> pipe.
[0]
[0]
[0]hybridise(
[0]
[0]hybrid=
[0]
[0]`mixed model', pipes=
[0]
[0][`N_sphere', `C_ellipsoid'])
This hybrid data pipe can then be compared via model selection to a data pipe whereby the entire protein is assumed to have a single diffusion tensor.
The requirements for data pipes to be hybridised is that the molecules, sequences, and spin systems for all the data pipes is the same, and that no spin system is allowed to be selected in two or more data pipes. The selections must not overlap to allow for rigorous statistical comparisons.
Function for switching between data pipes.
pipe_name: The name of the data pipe.
This function will switch from the current data pipe to the given data pipe.
To switch to the `ellipsoid' data pipe, type:
relax> pipe.
[0]
[0]switch(
[0]
[0]`ellipsoid')
relax> pipe.
[0]
[0]switch(
[0]
[0]pipe_name=
[0]
[0]`ellipsoid')
Apply the PyMOL cartoon style and colour by secondary structure.
This function applies the PyMOL cartoon style which is equivalent to hiding everything and clicking on show cartoon. It also colours the cartoon with red helices, yellow strands, and green loops. The following commands are executed:
where file is the file name without the `.pdb' extension.
To apply this user function, type:
relax> pymol.
[0]
[0]
[0]cartoon(
[0]
[0])
Function for clearing the PyMOL command history.
Function for executing a user supplied PyMOL command.
command: The PyMOL command to execute.
This user function allows you to pass PyMOL commands to the program. This can be useful for automation or scripting.
To reinitialise the PyMOL instance, type:
relax> pymol.
[0]
[0]
[0]command(
[0]
[0]"reinitialise")
Display, as designed, the cone PDB geometric object from the N-state model.
file: The name of the PDB file containing the cone geometric object.
The PDB file containing the geometric object must be created using the complementary `n_state_model.cone_pdb()' user function.
The cone PDB file is read in using the command:
The average CoM-pivot point vector, the residue `AVE' is displayed using the commands:
The cone object, the residue `CON', is displayed using the commands:
Function for executing PyMOL macros.
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
This function allows residues specific values to be mapped to a structure through PyMOL macros. Currently only the `classic' style, which is described below, is available.
The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default PyMOL colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.
To map the order parameter values,
, onto the structure using the classic style, type:
relax> pymol.
[0]
[0]macro_exec(
[0]
[0]`S2')
relax> pymol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2')
relax> pymol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic")
Function displaying the diffusion tensor PDB geometric object over the loaded PDB.
file: The name of the PDB file containing the tensor geometric object.
In executing this user function, a PDB file must have previously been loaded into this data pipe a geometric object or polygon representing the Brownian rotational diffusion tensor will be overlain with the loaded PDB file and displayed within PyMOL. The PDB file containing the geometric object must be created using the complementary `pdb.create_diff_tensor_pdb()' user function.
The tensor PDB file is read in using the command:
The centre of mass residue `COM' is displayed using the commands:
The axes of the diffusion tensor, the residue `AXS', is displayed using the commands:
The simulation axes, the residues `SIM', are displayed using the commands:
Function displaying the PDB file representation of the XH vector distribution.
file: The name of the PDB file containing the vector distribution.
A PDB file of the macromolecule must have previously been loaded as the vector distribution will be overlain with the macromolecule within PyMOL. The PDB file containing the vector distribution must be created using the complementary `pdb.create_vector_dist()' user function.
The vector distribution PDB file is read in using the command:
Function for viewing the collection of molecules extracted from the PDB file.
relax> pymol.
[0]
[0]view(
[0]
[0])
Function for creating PyMOL macros.
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
file: The name of the file.
dir: The directory name.
force: A flag which, if set to True, will cause the file to be overwritten.
This function allows residues specific values to be mapped to a structure through the creation of a PyMOL macro which can be executed in PyMOL by clicking on `File, Macro, Execute User...'. Currently only the `classic' style, which is described below, is available.
The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default PyMOL colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the PyMOL list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.
To create a PyMOL macro mapping the order parameter values,
, onto the structure using the classic style, type:
relax> pymol.
[0]
[0]write(
[0]
[0]`S2')
relax> pymol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2')
relax> pymol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic", file=
[0]
[0]`s2.
[0]
[0]mac', dir=
[0]
[0]`pymol')
The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.
(see table 10.20)
The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.
(see table 10.21)
Back calculate RDCs.
align_id: The alignment ID string.
Calculate the RDC Q-factor for the selected spins.
spin_id: The spin ID string for restricting to subset of all selected spins.
For this function to work, the back-calculated RDC data must first be generated by the analysis specific code. Otherwise a warning will be given.
To calculate the RDC Q-factor for only the spins `@H26', `@H27', and `@H28', type one of:
relax> rdc.
[0]
[0]
[0]calc_q_factors(
[0]
[0]`@H26 & @H27 & @H28')
relax> rdc.
[0]
[0]
[0]calc_q_factors(
[0]
[0]spin_id=
[0]
[0]`@H26 & @H27 & @H28')
Copy RDC data from pipe_from to pipe_to.
pipe_from: The name of the pipe to copy the RDC data from.
pipe_to: The name of the pipe to copy the RDC data to.
align_id: The alignment ID string.
This function will copy RDC data from `pipe_from' to `pipe_to'. If align_id is not given then all RDC data will be copied, otherwise only a specific data set will be.
To copy all RDC data from pipe `m1' to pipe `m9', type one of:
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', align_id=
[0]
[0]None)
To copy only the `Th' RDC data from `m3' to `m6', type one of:
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `Th')
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', align_id=
[0]
[0]`Th')
Generate a correlation plot of the measured vs. the back-calculated RDCs.
format: The format of the plot data.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
Two formats are currently supported. If format is set to `grace', then a Grace plot file will be created. If the format arg is set to None, then a plain text list of the measured and back-calculated data will be created.
To create a Grace plot of the data, type:
relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0])
To create a plain text list of the measured and back-calculated data, type one of:
relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0]None)
relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0]format=
[0]
[0]None)
Delete the RDC data corresponding to the alignment ID.
align_id: The alignment ID string.
To delete the RDC data corresponding to align_id=`PH_gel', type:
relax> rdc.
[0]
[0]
[0]delete(
[0]
[0]`PH_gel')
Display the RDC data corresponding to the alignment ID.
align_id: The alignment ID string.
To display the `phage' RDC data, type:
relax> rdc.
[0]
[0]
[0]display(
[0]
[0]`phage')
align_id: The alignment ID string.
file: The name of the file containing the RDC data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
neg_g_corr: A flag which is used to correct for the negative gyromagnetic ratio of 15N.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
If neg_g_corr is set to True, a sign inversion will be applied to all RDC values to be loaded.
The following commands will read the RDC data out of the file `Tb.txt' where the columns are separated by the symbol `,', and store the RDCs under the ID `Tb'.
relax> rdc.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', sep=
[0]
[0]`,')
If the individual spin RDC errors are located in the file `rdc_err.txt' in column number 5, then to read these values into relax, type one of:
relax> rdc.
[0]
[0]read(
[0]
[0]`phage', `rdc_err.
[0]
[0]txt', error_col=
[0]
[0]5)
relax> rdc.
[0]
[0]read(
[0]
[0]align_id=
[0]
[0]`phage', file=
[0]
[0]`rdc_err.
[0]
[0]txt', error_col=
[0]
[0]5)
If the RDCs correspond to the `N' spin and other spin types such as 1H, 13C, etc. are loaded into relax, then type:
relax> rdc.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@N')
Set optimisation weights on the RDC data.
align_id: The alignment ID string.
spin_id: The spin ID string.
weight: The weighting value.
This function can be used to force the RDC to contribute more or less to the chi-squared optimisation statistic. The higher the value, the more importance the RDC will have.
align_id: The alignment ID string.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory. The `align_id' argument are required for selecting which RDC data set will be written to file.
Function for back calculating relaxation data.
ri_id: The relaxation data ID string.
ri_type: The relaxation data type, ie `R1', `R2', or `NOE'.
frq: The spectrometer frequency in Hz.
Copy relaxation data from one pipe to another.
pipe_from: The name of the pipe to copy the relaxation data from.
pipe_to: The name of the pipe to copy the relaxation data to.
ri_id: The relaxation data ID string.
This function will copy relaxation data from `pipe_from' to `pipe_to'. If ri_id is not given then all relaxation data will be copied, otherwise only a specific data set will be copied.
To copy all relaxation data from pipe `m1' to pipe `m9', type one of:
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', ri_id=
[0]
[0]None)
To copy only the NOE relaxation data with the ID string of `NOE_800' from `m3' to `m6', type one of:
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `NOE_800')
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', ri_id=
[0]
[0]`NOE_800')
Delete the data corresponding to the relaxation data ID string.
ri_id: The relaxation data ID string.
To delete the relaxation data corresponding to the ID `NOE_600', type:
relax> relax_data.
[0]
[0]
[0]delete(
[0]
[0]`NOE_600')
Display the data corresponding to the relaxation data ID string.
ri_id: The relaxation data ID string.
To display the NOE relaxation data at 600 MHz with the ID string `NOE_600', type:
relax> relax_data.
[0]
[0]
[0]display(
[0]
[0]`NOE_600')
Specify the type of peak intensity measurement used - 
.e. height or volume.
ri_id: The relaxation data ID string.
type: The peak intensity type.
This user function is essential for BMRB data deposition. This is used to specify whether peak heights or peak volumes were measured. The two currently allowed values for the type argument are `height' and `volume'.
Read R
, R
, or NOE relaxation data from a file.
ri_id: The relaxation data ID string.
ri_type: The relaxation data type, ie `R1', `R2', or `NOE'.
frq: The spectrometer frequency in Hz.
file: The name of the file containing the relaxation data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The relaxation data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The frequency label argument can be anything as long as data collected at the same field strength have the same label.
The following commands will read the protein NOE relaxation data collected at 600 MHz out of a file called `noe.600.out' where the residue numbers, residue names, data, errors are in the first, second, third, and forth columns respectively.
relax> relax_data.
[0]
[0]read(
[0]
[0]`NOE_600', `NOE', 599.7 * 1e6, `noe.600.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4)
relax> relax_data.
[0]
[0]read(
[0]
[0]ri_id=
[0]
[0]`NOE_600', ri_type=
[0]
[0]`NOE', frq=
[0]
[0]600.0 * 1e6, file=
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4)
The following commands will read the R
data out of the file `r2.out' where the residue numbers, residue names, data, errors are in the second, third, fifth, and sixth columns respectively. The columns are separated by commas.
relax> relax_data.
[0]
[0]read(
[0]
[0]`R2_800', `R2', 8.0 * 1e8, `r2.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]3, data_col=
[0]
[0]5, error_col=
[0]
[0]6, sep=
[0]
[0]`,')
relax> relax_data.
[0]
[0]read(
[0]
[0]ri_id=
[0]
[0]`R2_800', ri_type=
[0]
[0]`R2', frq=
[0]
[0]8.0*1e8, file=
[0]
[0]`r2.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]3, data_col=
[0]
[0]5, error_col=
[0]
[0]6, sep=
[0]
[0]`,')
The following commands will read the R
data out of the file `r1.out' where the columns are separated by the symbol `%'
relax> relax_data.
[0]
[0]read(
[0]
[0]`R1_300', `R1', 300.1 * 1e6, `r1.
[0]
[0]out', sep=
[0]
[0]`%')
Specify the temperature calibration method used.
ri_id: The relaxation data ID string.
method: The calibration method.
This user function is essential for BMRB data deposition. The currently allowed methods are
Other strings will be accepted if supplied.
Specify the temperature control method used.
ri_id: The relaxation data ID string.
method: The control method.
This user function is essential for BMRB data deposition. The currently allowed methods are
Write relaxation data to a file.
ri_id: The relaxation data ID string.
file: The name of the file.
dir: The directory name.
bc: A flag which if True will cause the back calculated relaxation data to be written to file rather than the actual data.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory. The `ri_id' argument is required for selecting which relaxation data to write to file.
Function for setting the relaxation time period associated with each spectrum.
time: The time, in seconds, of the relaxation period.
spectrum_id: The spectrum identification string.
Peak intensities should be loaded before calling this user function via the `spectrum.read_intensities()' user function. The intensity values will then be associated with a spectrum identifier. To associate each spectrum identifier with a time point in the relaxation curve prior to optimisation, this user function should be called.
Function for the selection of the relaxation curve type.
model: The type of relaxation curve to fit.
The supported relaxation experiments include the default two parameter exponential fit, selected by setting the `fit_type' argument to `exp', and the three parameter inversion recovery experiment in which the peak intensity limit is a non-zero value, selected by setting the argument to `inv'.
The parameters of these two models are
Reset relax.
All of the data of the relax data storage object will be erased and hence relax will return to its initial state.
Function for copying all data associated with a residue.
pipe_from: The data pipe containing the residue from which the data will be copied. This defaults to the current data pipe.
res_from: The residue identifier string of the residue to copy the data from.
pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.
res_to: The residue identifier string of the residue to copy the data to.
This function will copy all the data associated with the identified residue to the new, non-existent residue. The new residue must not already exist.
To copy the residue data from residue 1 to the new residue 2, type:
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`:1', res_to=
[0]
[0]`:2')
To copy residue 1 of the molecule `Old mol' to residue 5 of the molecule `New mol', type:
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`#Old mol:1', res_to=
[0]
[0]`#New mol:5')
To copy the residue data of residue 1 from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`:1', pipe_to=
[0]
[0]`m2')
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', res_from=
[0]
[0]`:1', pipe_to=
[0]
[0]`m2', res_to=
[0]
[0]`:1')
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for creating a new residue.
res_num: The residue number.
res_name: The name of the residue.
mol_name: The name of the molecule to add the residue to.
Using this function a new sequence can be generated without using the sequence user functions. However if the sequence already exists, the new residue will be added to the end of the residue list (the residue numbers of this list need not be sequential). The same residue number cannot be used more than once. A corresponding single spin system will be created for this residue. The spin system number and name or additional spin systems can be added later if desired.
The following sequence of commands will generate the sequence 1 ALA, 2 GLY, 3 LYS:
relax> residue.
[0]
[0]
[0]create(
[0]
[0]1, `ALA')
relax> residue.
[0]
[0]
[0]create(
[0]
[0]2, `GLY')
relax> residue.
[0]
[0]
[0]create(
[0]
[0]3, `LYS')
Function for deleting residues.
res_id: The residue identifier string.
This function can be used to delete a single or sets of residues. See the identification string documentation below for more information. If spin system/atom ids are included a RelaxError will be raised.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for displaying information about the residue(s).
res_id: The residue identification string.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for naming residues.
res_id: The residue identification string corresponding to one or more residues.
name: The new name.
force: A flag which if True will cause the residue to be renamed.
This function simply allows residues to be named (or renamed).
The following sequence of commands will rename the sequence {1 ALA, 2 GLY, 3 LYS} to {1 XXX, 2 XXX, 3 XXX}:
relax> residue.
[0]
[0]name(
[0]
[0]`:1', `XXX', force=
[0]
[0]True)
relax> residue.
[0]
[0]name(
[0]
[0]`:2', `XXX', force=
[0]
[0]True)
relax> residue.
[0]
[0]name(
[0]
[0]`:3', `XXX', force=
[0]
[0]True)
Alternatively:
relax> residue.
[0]
[0]name(
[0]
[0]`:1,2,3', `XXX', force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for numbering residues.
res_id: The residue identification string corresponding to a single residue.
number: The new residue number.
force: A flag which if True will cause the residue to be renumbered.
This function simply allows residues to be numbered. The new number cannot correspond to an existing residue.
The following sequence of commands will renumber the sequence {1 ALA, 2 GLY, 3 LYS} to {101 ALA, 102 GLY, 103 LYS}:
relax> residue.
[0]
[0]number(
[0]
[0]`:1', 101, force=
[0]
[0]True)
relax> residue.
[0]
[0]number(
[0]
[0]`:2', 102, force=
[0]
[0]True)
relax> residue.
[0]
[0]number(
[0]
[0]`:3', 103, force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for displaying the results.
This will print to screen (STDOUT) the results contained within the current data pipe.
Function for reading results from a file.
file: The name of the file to read results from.
dir: The directory where the file is located.
To search for the results file in the current working directory, set dir to None.
This function is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.
Function for writing results to a file.
file: The name of the file to output results to. The default is `results'. Optionally this can be a file object, or any object with a write() method.
dir: The directory name.
compress_type: The type of compression to use when creating the file.
force: A flag which if True will cause the results file to be overwritten.
To place the results file in the current working directory, set dir to None. If dir is set to the special name `pipe_name', then the results file will be placed into a directory with the same name as the current data pipe.
The default behaviour of this function is to compress the file using bzip2 compression. If the extension `.bz2' is not included in the file name, it will be added. The compression can, however, be changed to either no compression or gzip compression. This is controlled by the compress_type argument which can be set to
The complementary read function will automatically handle the compressed files.
Function for selecting all spins.
To select all spins, simply type:
relax> select.
[0]
[0]
[0]all(
[0]
[0])
Function for selecting the spins contained in a file.
file: The name of the file containing the list of spins to select.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
boolean: The boolean operator specifying how spins should be selected.
change_all: A flag specifying if all other spins should be changed.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
Empty lines and lines beginning with a hash are ignored.
The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified in the file to be deselected.
To select all residues listed with residue numbers in the first column of the file `isolated_peaks', type one of:
relax> select.
[0]
[0]read(
[0]
[0]`isolated_peaks', res_num_col=
[0]
[0]1)
relax> select.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`isolated_peaks', res_num_col=
[0]
[0]1)
To select the spins in the second column of the relaxation data file `r1.600' while deselecting all other spins, for example type:
relax> select.
[0]
[0]read(
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
relax> select.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
The `boolean' keyword argument can be used to change how spin systems are selected. The allowed values are: `OR', `NOR', `AND', `NAND', `XOR', `XNOR'. The following table details how the selections will occur for the different boolean operators.
(see table 10.22)
Function for the reversal of the spin selection for the given spins.
spin_id: The spin identification string.
By supplying the spin_id argument, a subset of spin can have their selection status reversed.
To select all currently deselected spins and deselect those which are selected type:
relax> select.
[0]
[0]reverse(
[0]
[0])
Function for selecting specific spins.
spin_id: The spin identification string.
boolean: The boolean operator specifying how spins should be selected.
change_all: A flag specifying if all other spins should be changed.
The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified by `spin_id' to be selected.
To select only glycines and alanines, assuming they have been loaded with the names GLY and ALA, type one of:
relax> select.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:GLY|:ALA')
To select residue 5 CYS in addition to the currently selected residues, type one of:
relax> select.
[0]
[0]spin(
[0]
[0]`:5')
relax> select.
[0]
[0]spin(
[0]
[0]`:5&:CYS')
relax> select.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:5&:CYS')
Copy the molecule, residue, and spin sequence data from one data pipe to another.
pipe_from: The name of the data pipe to copy the sequence data from.
pipe_to: The name of the data pipe to copy the sequence data to.
This function will copy the sequence data between data pipes. The destination data pipe must not contain any sequence data. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe (hence giving one argument is essential).
To copy the sequence from the data pipe `m1' to the current data pipe, type:
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]`m1')
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1')
To copy the sequence from the current data pipe to the data pipe `m9', type:
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m9')
To copy the sequence from the data pipe `m1' to `m2', type:
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')
Function for displaying sequences of molecules, residues, and/or spins.
sep: The column separator (the default of None corresponds to white space).
mol_name_flag: A flag whic if True will cause the molecule name column to be shown.
res_num_flag: A flag whic if True will cause the residue number column to be shown.
res_name_flag: A flag whic if True will cause the residue name column to be shown.
spin_num_flag: A flag whic if True will cause the spin number column to be shown.
spin_name_flag: A flag whic if True will cause the spin name column to be shown.
Read the molecule, residue, and spin sequence from a file.
file: The name of the file containing the sequence data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The following commands will read protein backbone 15N sequence data out of a file called `seq' where the residue numbers and names are in the first and second columns respectively:
relax> sequence.
[0]
[0]read(
[0]
[0]`seq')
relax> sequence.
[0]
[0]read(
[0]
[0]`seq', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`seq', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, sep=
[0]
[0]None)
The following commands will read the residue sequence out of the file `noe.out' which also contains the NOE values:
relax> sequence.
[0]
[0]read(
[0]
[0]`noe.
[0]
[0]out')
relax> sequence.
[0]
[0]read(
[0]
[0]`noe.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`noe.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)
The following commands will read the sequence out of the file `noe.600.out' where the residue numbers are in the second column, the names are in the sixth column and the columns are separated by commas:
relax> sequence.
[0]
[0]read(
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]6, sep=
[0]
[0]`,')
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]6, sep=
[0]
[0]`,')
The following commands will read the RNA residues and atoms (including C2, C5, C6, C8, N1, and N3) from the file `500.NOE', where the residue number, residue name, spin number, and spin name are in the first to fourth columns respectively:
relax> sequence.
[0]
[0]read(
[0]
[0]`500.
[0]
[0]NOE', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, spin_num_col=
[0]
[0]3, spin_name_col=
[0]
[0]4)
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`500.
[0]
[0]NOE', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, spin_num_col=
[0]
[0]3, spin_name_col=
[0]
[0]4)
Write the molecule, residue, and spin sequence to a file.
file: The name of the file.
dir: The directory name.
sep: The column separator (the default of None corresponds to white space).
mol_name_flag: A flag whic if True will cause the molecule name column to be shown.
res_num_flag: A flag whic if True will cause the residue number column to be shown.
res_name_flag: A flag whic if True will cause the residue name column to be shown.
spin_num_flag: A flag whic if True will cause the spin number column to be shown.
spin_name_flag: A flag whic if True will cause the spin name column to be shown.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory.
Set the baseplane RMSD of a given spin in a spectrum for error analysis.
error: The baseplane RMSD error value.
spectrum_id: The spectrum identification string.
spin_id: The spin identification string.
The spectrum_id argument identifies the spectrum associated with the error and must correspond to a previously loaded set of intensities. If the `spin_id' argument is left on the default of None, then the error value for all spins will be set to the supplied value.
Function for performing an error analysis for peak intensities.
This user function must only be called after all peak intensities have been loaded and all other necessary spectral information set. This includes the baseplane RMSD and the number of points used in volume integration, both of which are only used if spectra have not been replicated.
Six different types of error analysis are supported depending on whether peak heights or volumes are supplied, whether noise is determined from replicated spectra or the RMSD of the baseplane noise, and whether all spectra or only a subset have been duplicated. These are:
(see table 10.23)
When none of the spectra have been replicated, then the peak height errors are calculated using the RMSD of the baseplane noise, the value of which is set by the spectrum.baseplane_rmsd() user function. This results in a different error per peak per spectrum. The standard deviation error measure for the peak height, sigma_I, is set to the RMSD value.
When spectra are replicated, the variance for a single spin at a single replicated spectra set is calculated by the formula
sigma^2 = sum({Ii - Iav}^2) / (n - 1) ,
where sigma^2 is the variance, sigma is the standard deviation,
is the size of the replicated spectra set with
being the corresponding index, Ii is the peak intensity for spectrum
, and Iav is the mean over all spectra
.e. the sum of all peak intensities divided by
.
As the value of
in the above equation is always very low since normally only a couple of spectra are collected per replicated spectra set, the variance of all spins is averaged for a single replicated spectra set. Although this results in all spins having the same error, the accuracy of the error estimate is significantly improved.
If there are in addition to the replicated spectra loaded peak intensities which only consist of a single spectrum,
.e. not all spectra are replicated, then the variances of replicated replicated spectra sets will be averaged. This will be used for the entire experiment so that there will be only a single error value for all spins and for all spectra.
If all spectra are collected in duplicate (triplicate or higher number of spectra are supported), the each replicated spectra set will have its own error estimate. The error for a single peak is calculated as when partially replicated spectra are collected, and these are again averaged to give a single error per replicated spectra set. However as all replicated spectra sets will have their own error estimate, variance averaging across all spectra sets will not be performed.
The method of error analysis when no spectra have been replicated and peak volumes are used is highly dependent on the integration method. Many methods simply sum the number of points within a fixed region, either a box or oval object. The number of points used, N, must be specified by another user function in this class. Then the error is simply given by the sum of variances:
sigma_vol^2 = sigma_i^2 * N,
where sigma_vol is the standard deviation of the volume, sigma_i is the standard deviation of a single point assumed to be equal to the RMSD of the baseplane noise, and N is the total number of points used in the summation integration method. For a box integration method, this converts to the Nicholson, Kay, Baldisseri, Arango, Young, Bax, and Torchia (1992) Biochemistry, 31: 5253-5263 equation:
sigma_vol = sigma_i * sqrt(n*m),
where
and 
are the dimensions of the box. Note that a number of programs, for example peakint (http://hugin.ethz.ch/wuthrich/software/xeasy/xeasy_m15.html) does not use all points within the box. And if the number N can not be determined, this category of error analysis is not possible.
Also note that non-point summation methods, for example when line shape fitting is used to determine peak volumes, the equations above cannot be used. Hence again this category of error analysis cannot be used. This is the case for one of the three integration methods used by Sparky (http://www.cgl.ucsf.edu/home/sparky/manual/peaks.html#Integration). And if fancy techniques are used, for example as Cara does to deconvolute overlapping peaks (http://www.cara.ethz.ch/Wiki/Integration), this again makes this error analysis impossible.
When peak volumes are measured by any integration method and a few of the spectra are replicated, then the intensity errors are calculated identically as described in the `Peak heights with partially replicated spectra' section above.
With all spectra replicated and again using any integration methodology, the intensity errors can be calculated as described in the `Peak heights with all spectra replicated' section above.
Set the number of summed points used in volume integration of a given spin in a spectrum.
N: The number of points used by the summation volume integration method.
spectrum_id: The spectrum identification string.
spin_id: The spin identification string.
For a complete description of which integration methods and how many points N are used for different integration techniques, please read the spectrum.error_analysis() documentation.
The spectrum_id argument identifies the spectrum associated with the value of N and must correspond to a previously loaded set of intensities. If the `spin_id' argument is left on the default of None, then the number of summed points for all spins will be set to the supplied value.
Function for reading peak intensities from a file for NOE calculations.
file: The name of the file containing the intensity data.
dir: The directory where the file is located.
spectrum_id: The spectrum identification string.
heteronuc: The name of the heteronucleus as specified in the peak intensity file.
proton: The name of the proton as specified in the peak intensity file.
int_col: The column containing the peak intensity data (used by the generic intensity file format).
int_method: The integration method.
spin_id_col: The spin ID string column used by the generic intensity file format (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column used by the generic intensity file format (alternative to the spin_id_col).
res_num_col: The residue number column used by the generic intensity file format (alternative to the spin_id_col).
res_name_col: The residue name column used by the generic intensity file format (alternative to the spin_id_col).
spin_num_col: The spin number column used by the generic intensity file format (alternative to the spin_id_col).
spin_name_col: The spin name column used by the generic intensity file format (alternative to the spin_id_col).
sep: The column separator used by the generic intensity format (the default is white space).
spin_id: The spin ID string used by the generic intensity file format to restrict the loading of data to certain spin subsets.
ncproc: The Bruker specific FID intensity scaling factor.
The peak intensity can either be from peak heights or peak volumes.
The `spectrum_id' argument is a label which is subsequently utilised by other user functions. If this identifier matches that of a previously loaded set of intensities, then this indicates a replicated spectrum.
The `heteronuc' and `proton' arguments should be set respectively to the name of the heteronucleus and proton in the file. Only those lines which match these labels will be used.
The `int_method' argument is required for the subsequent error analysis. When peak heights are measured, this argument should be set to `height'. Volume integration methods are a bit varied and hence two values are accepted. If the volume integration involves pure point summation, with no deconvolution algorithms or other methods affecting peak heights, then the argument should be set to `point sum'. All other volume integration methods, e.g. line shape fitting, the argument should be set to `other'.
If a series of intensities extracted from Bruker FID files processed in Topspin or XWinNMR are to be compared, the ncproc parameter may need to be supplied. This is because this FID is stored using integer representation and is scaled using ncproc to avoid numerical truncation artifacts. If two spectra have significantly different maximal intensities, then ncproc will be different for both. The intensity scaling is binary,
.e. 2**ncproc. Therefore if spectrum A has an ncproc of 6 and and spectrum B a value of 7, then a reference intensity in B will be double that of A. Internally, relax stores the intensities scaled by 2**ncproc.
The peak list or intensity file will be automatically determined.
Sparky peak list: The file should be a Sparky peak list saved after typing the command `lt'. The default is to assume that columns 0, 1, 2, and 3 (1
, 2
, 3
, and 4
) contain the Sparky assignment, w1, w2, and peak intensity data respectively. The frequency data w1 and w2 are ignored while the peak intensity data can either be the peak height or volume displayed by changing the window options. If the peak intensity data is not within column 3, set the argument `int_col' to the appropriate value (column numbering starts from 0 rather than 1).
XEasy peak list: The file should be the saved XEasy text window output of the list peak entries command, `tw' followed by `le'. As the columns are fixed, the peak intensity column is hardwired to number 10 (the 11
column) which contains either the peak height or peak volume data. Because the columns are fixed, the `int_col' argument will be ignored.
NMRView: The file should be a NMRView peak list. The default is to use column 16 (which contains peak heights) for peak intensities. To use use peak volumes (or evolumes), int_col must be set to 15.
Generic intensity file: This is a generic format which can be created by scripting to support non-supported peak lists. It should contain in the first few columns enough information to identify the spin. This can include columns for the molecule name, residue number, residue name, spin number, and spin name, with each optional type positioned with the *name_col and *num_col arguments. Alternatively a spin ID string column can be used. The peak intensities can be placed in another column specified by the int_col argument. Intensities from multiple spectra can be placed into different columns, and these can then be specified simultaneously by setting the int_col argument to a list of columns. This list must be matched by setting the spectrum_id argument to list of the same length. If columns are delimited by a character other than whitespace, this can be specified with the sep argument. The spin_id argument can be used to restrict the loading to specific spin subsets.
To read the reference and saturated spectra peak heights from the Sparky formatted files `ref.list' and `sat.list', type:
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`ref.
[0]
[0]list', spectrum_id=
[0]
[0]`ref')
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`sat.
[0]
[0]list', spectrum_id=
[0]
[0]`sat')
To read the reference and saturated spectra peak heights from the XEasy formatted files `ref.text' and `sat.text', type:
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`ref.
[0]
[0]text', spectrum_id=
[0]
[0]`ref')
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`sat.
[0]
[0]text', spectrum_id=
[0]
[0]`sat')
Function for specifying which spectra are replicates.
spectrum_ids: The list of replicated spectra identification strings.
This user function is used to identify which loaded spectra are replicates of each other. This is very important for error analysis.
To specify that the NOE spectra labelled `ref1', `ref2', and `ref3' are the same spectrum replicated, type one of:
relax> spectrum.
[0]
[0]replicated(
[0]
[0][`ref1', `ref2', `ref3'])
relax> spectrum.
[0]
[0]replicated(
[0]
[0]spectrum_ids=
[0]
[0][`ref1', `ref2', `ref3'])
To specify that the two R
spectra `ncyc2' and `ncyc2
' are the same time point, type:
relax> spectrum.
[0]
[0]replicated(
[0]
[0][`ncyc2', `ncyc2b'])
Function for copying all data associated with a spin.
pipe_from: The data pipe containing the spin from which the data will be copied. This defaults to the current data pipe.
spin_from: The spin identifier string of the spin to copy the data from.
pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.
spin_to: The spin identifier string of the spin to copy the data to.
This function will copy all the data associated with the identified spin to the new, non-existent spin. The new spin must not already exist.
To copy the spin data from spin 1 to the new spin 2, type:
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`@1', spin_to=
[0]
[0]`@2')
To copy spin 1 of the molecule `Old mol' to spin 5 of the molecule `New mol', type:
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`#Old mol@1', spin_to=
[0]
[0]`#New mol@5')
To copy the spin data of spin 1 from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`@1', pipe_to=
[0]
[0]`m2')
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', spin_from=
[0]
[0]`@1', pipe_to=
[0]
[0]`m2', spin_to=
[0]
[0]`@1')
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for creating a new spin.
spin_num: The spin number.
spin_name: The name of the spin.
res_num: The number of the residue to add the spin to.
res_name: The name of the residue to add the spin to.
mol_name: The name of the molecule to add the spin to.
This function will add a new spin data container to the relax data storage object. The same spin number cannot be used more than once.
The following sequence of commands will generate the sequence 1 C4, 2 C9, 3 C15:
relax> spin.
[0]
[0]
[0]create(
[0]
[0]1, `C4')
relax> spin.
[0]
[0]
[0]create(
[0]
[0]2, `C9')
relax> spin.
[0]
[0]
[0]create(
[0]
[0]3, `C15')
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for creating a spin system representing a pseudo-atom.
spin_name: The name of the pseudo-atom spin.
spin_num: The spin number.
res_id: The molecule and residue ID string identifying the position to add the pseudo-spin to.
mol_id: The molecule ID string identifying the molecule to add the pseudo-spin to.
members: A list of the atoms the pseudo-atom is composed of.
averaging: The positional averaging technique.
This function will create a spin data container representing a number of pre-existing spin containers as a pseudo-atom. The optional spin number must not already exist.
The following will create the pseudo-atom named `Q9' consisting of the protons `@H16', `@H17', `@H18':
relax> spin.
[0]
[0]
[0]create_pseudo(
[0]
[0]`Q9', members=
[0]
[0][`@H16', `@H17', `@H18'])
Function for deleting spins.
spin_id: The spin identifier string.
This function can be used to delete a single or sets of spins. See the identification string documentation below for more information.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for displaying information about the spin(s).
spin_id: The spin identification string.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Set the element type of the spin.
spin_id: The spin identification string corresponding to one or more spins.
element: The IUPAC element name.
force: A flag which if True will cause the element to be changed.
This function allows the element type of the spins to be set.
The set all spins of residue 1 to be carbons, type one of:
relax> spin.
[0]
[0]
[0]element(
[0]
[0]`@1', `C', force=
[0]
[0]True)
relax> spin.
[0]
[0]
[0]element(
[0]
[0]spin_id=
[0]
[0]`@1', element=
[0]
[0]`C', force=
[0]
[0]True)
Function for naming spins.
spin_id: The spin identification string corresponding to one or more spins.
name: The new name.
force: A flag which if True will cause the spin to be renamed.
This function simply allows spins to be named (or renamed).
The following sequence of commands will rename the sequence {1 C1, 2 C2, 3 C3} to {1 C11, 2 C12, 3 C13}:
relax> spin.
[0]
[0]name(
[0]
[0]`@1', `C11', force=
[0]
[0]True)
relax> spin.
[0]
[0]name(
[0]
[0]`@2', `C12', force=
[0]
[0]True)
relax> spin.
[0]
[0]name(
[0]
[0]`@3', `C13', force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for numbering spins.
spin_id: The spin identification string corresponding to a single spin.
number: The new spin number.
force: A flag which if True will cause the spin to be renumbered.
This function simply allows spins to be numbered. The new number cannot correspond to an existing spin number.
The following sequence of commands will renumber the sequence {1 C1, 2 C2, 3 C3} to {-1 C1, -2 C2, -3 C3}:
relax> spin.
[0]
[0]number(
[0]
[0]`@1', -1, force=
[0]
[0]True)
relax> spin.
[0]
[0]number(
[0]
[0]`@2', -2, force=
[0]
[0]True)
relax> spin.
[0]
[0]number(
[0]
[0]`@3', -3, force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for loading a saved program state.
state: The file name, which can be a string or a file descriptor object, of a saved program state.
dir: The name of the directory in which the file is found.
force: A boolean flag which if True will cause the current program state to be overwritten.
This function is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.
Both the XML and pickled saved state formats are supported and automatically determined. For more advanced users, file descriptor objects are also supported. If the force flag is set to True, then the relax data store will be reset prior to the loading of the saved state.
The following commands will load the state saved in the file `save'.
relax> state.
[0]
[0]load(
[0]
[0]`save')
relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save')
Use one of the following commands to load the state saved in the bzip2 compressed file `save.bz2':
relax> state.
[0]
[0]load(
[0]
[0]`save')
relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save')
relax> state.
[0]
[0]load(
[0]
[0]`save.
[0]
[0]
[0]bz2')
relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save.
[0]
[0]
[0]bz2', force=
[0]
[0]True)
Function for saving the program state.
state: The file name, which can be a string or a file descriptor object, to save the current program state in.
dir: The name of the directory in which to place the file.
compress_type: The type of compression to use when creating the file.
force: A boolean flag which if set to True will cause the file to be overwritten.
pickle: A flag which if true will cause the state file to be a pickled object rather than the default XML format.
This user function will place the program state - the relax data store - into a file for later reloading or reference. The default format is an XML formatted file, but this can be changed to a Python pickled object through the pickle flag. Note, the pickle format is not human readable and often is not compatible with newer relax versions.
The default behaviour of this function is to compress the file using bzip2 compression. If the extension `.bz2' is not included in the file name, it will be added. The compression can, however, be changed to either no compression or gzip compression. This is controlled by the compress_type argument which can be set to
The following commands will save the current program state, uncompressed, into the file `save':
relax> state.
[0]
[0]save(
[0]
[0]`save', compress_type=
[0]
[0]0)
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save', compress_type=
[0]
[0]0)
The following commands will save the current program state into the bzip2 compressed file `save.bz2':
relax> state.
[0]
[0]save(
[0]
[0]`save')
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save')
relax> state.
[0]
[0]save(
[0]
[0]`save.
[0]
[0]
[0]bz2')
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save.
[0]
[0]
[0]bz2')
If the file `save' already exists, the following commands will save the current program state by overwriting the file.
relax> state.
[0]
[0]save(
[0]
[0]`save', force=
[0]
[0]True)
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save', force=
[0]
[0]True)
Create a PDB file to represent the diffusion tensor.
scale: Value for scaling the diffusion rates.
file: The name of the PDB file.
dir: The directory where the file is located.
force: A flag which, if set to True, will overwrite the any pre-existing file.
This function creates a PDB file containing an artificial geometric structure to represent the diffusion tensor. A structure must have previously been read into relax. The diffusion tensor is represented by an ellipsoidal, spheroidal, or spherical geometric object with its origin located at the centre of mass (of the selected residues). This diffusion tensor PDB file can subsequently read into any molecular viewer.
There are four different types of residue within the PDB. The centre of mass of the selected residues is represented as a single carbon atom of the residue `COM'. The ellipsoidal geometric shape consists of numerous H atoms of the residue `TNS'. The axes of the tensor, when defined, are presented as the residue `AXS' and consist of carbon atoms: one at the centre of mass and one at the end of each eigenvector. Finally, if Monte Carlo simulations were run and the diffusion tensor parameters were allowed to vary then there will be multiple `SIM' residues, one for each simulation. These are essentially the same as the `AXS' residue, representing the axes of the simulated tensors, and they will appear as a distribution.
As the Brownian rotational diffusion tensor is a measure of the rate of rotation about different axes - the larger the geometric object, the faster the diffusion of a molecule. For example the diffusion tensor of a water molecule is much larger than that of a macromolecule.
The effective global correlation time experienced by an XH bond vector, not to be confused with the Lipari and Szabo parameter
_e, will be approximately proportional to the component of the diffusion tensor parallel to it. The approximation is not exact due to the multiexponential form of the correlation function of Brownian rotational diffusion. If an XH bond vector is parallel to the longest axis of the tensor, it will be unaffected by rotations about that axis, which are the fastest rotations of the molecule, and therefore its effective global correlation time will be maximal.
To set the size of the diffusion tensor within the PDB frame the unit vectors used to generate the geometric object are first multiplied by the diffusion tensor (which has the units of inverse seconds) then by the scaling factor (which has the units of second Åand has the default value of 1.8e-6 s.Angstrom). Therefore the rotational diffusion rate per Åis equal the inverse of the scale value (which defaults to 5.56e5 s^-1.Angstrom^-1). Using the default scaling value for spherical diffusion, the correspondence between global correlation time,
diffusion rate, and the radius of the sphere for a number of discrete cases will be:
(see table 10.24)
The scaling value has been fixed to facilitate comparisons within or between publications, but can be changed to vary the size of the tensor geometric object if necessary. Reporting the rotational diffusion rate per Åwithin figure legends would be useful.
To create the tensor PDB representation, a number of algorithms are utilised. Firstly the centre of mass is calculated for the selected residues and is represented in the PDB by a C atom. Then the axes of the diffusion are calculated, as unit vectors scaled to the appropriate length (multiplied by the eigenvalue
,
,
,
,
, or
as well as the scale value), and a C atom placed at the position of this vector plus the centre of mass. Finally a uniform distribution of vectors on a sphere is generated using spherical coordinates. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These unit vectors, which are distributed within the PDB frame and are of 1 Åin length, are first rotated into the diffusion frame using a rotation matrix (the spherical diffusion tensor is not rotated). Then they are multiplied by the diffusion tensor matrix to extend the vector out to the correct length, and finally multiplied by the scale value so that the vectors reasonably superimpose onto the macromolecular structure. The last set of algorithms place all this information into a PDB file. The distribution of vectors are represented by H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines.
Create a PDB file representation of the distribution of XH bond vectors.
length: The length of the vectors in the PDB representation (meters).
file: The name of the PDB file.
dir: The directory to place the file into.
symmetry: A flag which if True will create a second chain with reversed XH bond orientations.
force: A flag which if True will overwrite the file if it already exists.
This function creates a PDB file containing an artificial vectors, the length of which default to the length argument of 20 Å. A structure must have previously been read into relax. The origin of the vector distribution is located at the centre of mass (of the selected residues). This vector distribution PDB file can subsequently be read into any molecular viewer.
Because of the symmetry of the diffusion tensor reversing the orientation of the XH bond vector has no effect. Therefore by setting the symmetry flag two chains `A' and `B' will be added to the PDB file whereby chain `B' is chain `A' with the XH bonds reversed.
Delete all structural information from the current data pipe.
This function will delete all the structural information.
Simply type:
relax> structure.
[0]
[0]
[0]delete(
[0]
[0])
Extract the atomic positions from the loaded structures for the given spins.
spin_id: The spin identification string.
ave_pos: A flag specifying if the position of the atom is to be averaged across models.
This function allows the atomic positions of the spins to be extracted from the loaded structures. This is automatically performed by the structure.load_spins() user function, but if the sequence information is generated in other ways, this user function allows the structural information to be obtained.
If the ave_pos flag is True, the average position of all models will be loaded into the spin container. If False, then the positions from all models will be loaded.
For a model-free backbone amide nitrogen analysis whereby the N spins have already been created, to obtain the backbone N positions from the file `1F3Y.pdb' (which is a single protein), type the following two user functions:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`1F3Y.
[0]
[0]pdb')
relax> structure.
[0]
[0]
[0]get_pos(
[0]
[0]spin_id=
[0]
[0]`@N')
Load spins from the structure into the relax data store.
spin_id: The spin identification string.
ave_pos: A flag specifying if the position of the atom is to be averaged across models.
This function allows a sequence to be generated within the relax data store using the atomic information from the structure already associated with this data pipe. The spin_id string is used to select which molecules, which residues, and which atoms will be recognised as spin systems within relax. If spin_id is left as None, then all molecules, residues, and atoms will be placed within the data store.
If the ave_pos flag is True, the average position of all models will be loaded into the spin container. If False, then the positions from all models will be loaded.
For a model-free backbone amide nitrogen analysis, to load just the backbone N sequence from the file `1F3Y.pdb' (which is a single protein), type the following two user functions:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`1F3Y.
[0]
[0]pdb')
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]`@N')
For an RNA analysis of adenine C8 and C2, guanine C8 and N1, cytidine C5 and C6, and uracil N3, C5, and C6, type the following series of commands (assuming that the PDB file with this atom naming has already been read):
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":A@C8")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":A@C2")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":G@C8")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":G@N1")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":C@C5")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":C@C6")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@N3")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@C5")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@C6")
Alternatively using some Python programming:
relax> for id in [":A@C8", ":A@C2", ":G@C8", ":G@N1", ":C@C5", ":C@C6", ":U@N3", ":U@C5", ":U@C6"]:
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]id)
Example for xyz file To load all C atoms from the `test.xyz' (which is a single molecule), type the following two user functions:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz')
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]`@*C*')
To load only the third atom from the xyz file, type the following user function: relax> structure.load_spins(spin_id=`@3')
file: The name of the PDB file.
dir: The directory where the file is located.
read_mol: If set, only the given molecule(s) will be read.
set_mol_name: Set the names of the read molecules.
read_model: If set, only the given model number(s) from the PDB file will be read.
set_model_num: Set the model numbers of the read molecules.
parser: The PDB parser used to read the file.
The reading of PDB files into relax is quite a flexible procedure allowing for both models, defined as an ensemble of the same molecule but with different atomic positions, and different molecules within the same model. One of more molecules can exist in one or more models. The flexibility allows PDB models to be converted into different molecules and different PDB files loaded as the same molecule but as different models. This flexibility is controlled by the four keyword arguments `read_mol', `set_mol_name', `read_model', and `set_model_num'.
A few different PDB parsers can be used to read the structural data. The choice of which to use depends on whether your PDB file is supported by that reader. These are selected by setting the `parser' argument to one of:
In a PDB file, the models are specified by the MODEL PDB record. All the supported PDB readers in relax recognise this. The molecule level is quite different between the Scientific Python and internal readers. For how Scientific Python defines molecules, please see its documentation. The internal reader is far simpler as it defines molecules using the TER PDB record. In both cases, the molecules will be numbered consecutively from 1.
The `set_mol_name' argument is used to name the molecules within the PDB (within one model). If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.
Note that relax will complain if it cannot work out what to do.
To load all structures from the PDB file `test.pdb' in the directory `~/pdb', including all models and all molecules, type one of:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', `~/pdb')
relax> structure.
[0]
[0]read_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', dir=
[0]
[0]`pdb')
To load the 10
model from the file `test.pdb' using the Scientific Python PDB parser and naming it `CaM', use one of:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM', parser=
[0]
[0]`scientific')
relax> structure.
[0]
[0]read_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM', parser=
[0]
[0]`scientific')
To load models 1 and 5 from the file `test.pdb' as two different structures of the same model, type one of:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', set_mol_name=
[0]
[0][`CaM_1', `CaM_2'], read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
To load the files `lactose_MCMM4_S1_1.pdb', `lactose_MCMM4_S1_2.pdb', `lactose_MCMM4_S1_3.pdb' and `lactose_MCMM4_S1_4.pdb' as models, type the following sequence of commands:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_1.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]1)
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_2.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]2)
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_3.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]3)
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_4.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]4)
The XYZ loading function.
file: The name of the XYZ file.
dir: The directory where the file is located.
read_mol: If set, only the given molecule(s) will be read.
set_mol_name: Set the names of the read molecules.
read_model: If set, only the given model number(s) from the XYZ file will be read.
set_model_num: Set the model numbers of the read molecules.
The XYZ files with different models, which defined as an ensemble of the same molecule but with different atomic positions, can be read into relax. If there are several molecules in one xyz file, please seperate them into different files and then load them individually. Loading different models and different molecules is controlled by the four keyword arguments `read_mol', `set_mol_name', `read_model', and `set_model_num'.
The `set_mol_name' argument is used to name the molecules within the XYZ (within one model). If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.
Note that relax will complain if it cannot work out what to do.
To load all structures from the XYZ file `test.xyz' in the directory `~/xyz', including all models and all molecules, type one of:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', `~/xyz')
relax> structure.
[0]
[0]read_xyz(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]xyz', dir=
[0]
[0]`xyz')
To load the 10
model from the file `test.xyz' and naming it `CaM', use one of:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM')
relax> structure.
[0]
[0]read_xyz(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM')
To load models 1 and 5 from the file `test.xyz' as two different structures of the same model, type one of:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', set_mol_name=
[0]
[0][`CaM_1', `CaM_2'], read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
To load the files `test_1.xyz', `test_2.xyz', `test_3.xyz' and `test_4.xyz' as models, type the following sequence of commands:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_1.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_1', set_model_num=
[0]
[0]1)
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_2.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_2', set_model_num=
[0]
[0]2)
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_3.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_3', set_model_num=
[0]
[0]3)
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_4.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_4', set_model_num=
[0]
[0]4)
Extract and store the bond vectors from the loaded structures in the spin container.
attached: The name of the second atom which attached to the spin of interest. Regular expression is allowed, for example `H*'.
spin_id: The spin identification string.
model: The model to extract bond vectors from (which if set to None will cause the vectors of all models to be extracted).
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
ave: A flag which if True will cause the bond vectors from all models to be averaged. If vectors from only one model is extracted, this argument will have no effect.
unit: A flag which if True will cause the unit vector to calculated rather than the full length bond vector.
For a number of types of analysis, bond vectors or unit bond vectors are required for the calculations. This user function allows these vectors to be extracted from the loaded structures. The bond vector will be that from the atom associated with the spin system loaded in relax to the bonded atom specified by the `attached' argument. For example if `attached' is set to `H' and the protein backbone amide spins `N' are loaded, the all `N-H' vectors will be extracted. But if set to `CA', all atoms named `CA' in the structures will be searched for and all `N-Ca' bond vectors will be extracted.
The extraction of vectors can occur in a number of ways. For example if an NMR structure with N models is loaded or if multiple molecules, from any source, of the same compound are loaded as different models, there are three options for extracting the bond vector. Firstly the bond vector of a single model can be extracted by setting the `model' argument. Secondly the bond vectors from all models can be extracted if `model' is None and `ave' is set to False. Thirdly, if `model' is None and `ave' is set to True, then a single vector which is the average for all models will be calculated.
To extract the XH vectors of the backbone amide nitrogens where in the PDB file the backbone nitrogen is called `N' and the attached atom is called `H', assuming multiple types of spin have already been loaded, type one of:
relax> structure.
[0]
[0]vectors(
[0]
[0]spin_id=
[0]
[0]`@N')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H', spin_id=
[0]
[0]`@N')
relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`H', spin_id=
[0]
[0]`@N')
If the attached atom is called `HN', type:
relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`HN', spin_id=
[0]
[0]`@N')
For the `CA' spin bonded to the `HA' proton, type:
relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`HA', spin_id=
[0]
[0]`@CA')
If you are working with RNA, you can use the residue name identifier to calculate the vectors for each residue separately. For example to calculate the vectors for all possible spins in the bases, type:
relax> structure.
[0]
[0]vectors(
[0]
[0]`H2', spin_id=
[0]
[0]`:A')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H8', spin_id=
[0]
[0]`:A')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H1', spin_id=
[0]
[0]`:G')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H8', spin_id=
[0]
[0]`:G')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H5', spin_id=
[0]
[0]`:C')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H6', spin_id=
[0]
[0]`:C')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H3', spin_id=
[0]
[0]`:U')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H5', spin_id=
[0]
[0]`:U')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H6', spin_id=
[0]
[0]`:U')
Alternatively, assuming the desired spins have been loaded, regular expression can be used:
relax> structure.
[0]
[0]vectors(
[0]
[0]`H*')
file: The name of the PDB file.
dir: The directory where the file is located.
model_num: The optional model to place in the PDB file.
force: A flag which, if set to True, will overwrite the any pre-existing file.
If the model_num argument is None, then all models will be written to a single file.
To write all models and molecules to the PDB file `ensemble.pdb' within the directory `~/pdb', type one of:
relax> structure.
[0]
[0]write_pdb(
[0]
[0]`ensemble.
[0]
[0]pdb', `~/pdb')
relax> structure.
[0]
[0]write_pdb(
[0]
[0]file=
[0]
[0]`ensemble.
[0]
[0]pdb', dir=
[0]
[0]`pdb')
To write model number 3 into the new file `test.pdb', use one of:
relax> structure.
[0]
[0]write_pdb(
[0]
[0]`test.
[0]
[0]pdb', model_num=
[0]
[0]3)
relax> structure.
[0]
[0]write_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', model_num=
[0]
[0]3)
Function which executes the user supplied shell command.
Specify the temperature of an experiment.
id: The experiment identification string.
temp: The temperature of the experiment.
This function allows the temperature of an experiment to be set. In certain analyses, for example those which use pseudocontact shift data, knowledge of the temperature is essential.
Copy spin specific data values from one data pipe to another.
pipe_from: The name of the pipe to copy from.
pipe_to: The name of the pipe to copy to.
Only one parameter may be selected, therefore the `param' argument should be a string.
If this function is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.
To copy the CSA values from the data pipe `m1' to `m2', type:
relax> value.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2', `CSA')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
Setting a parameter value may have no effect depending on which model-free model is chosen, for example if
values and
values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.
Note that the
values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:
/ (2.0 *
* frequency) ** 2
where:
is the chemical exchange value for the current frequency.
is in the namespace of relax, ie just type `pi'.
(see table 10.25)
In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.
(see table 10.26)
Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.
(see table 10.27)
Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle
of the third state is specified using the string `gamma2'.
(see table 10.28)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Display spin specific data values.
param: The parameter to display.
Only one parameter may be selected, therefore the `param' argument should be a string.
To show all CSA values, type:
relax> value.
[0]
[0]
[0]display(
[0]
[0]`CSA')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.29)
(see table 10.30)
(see table 10.31)
(see table 10.32)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Read spin specific data values from a file.
param: The parameter.
scaling: The factor to scale parameters by.
file: The name of the file containing the values.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
Only one parameter may be selected, therefore the `param' argument should be a string.
If this function is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.
To load 15N CSA values from the file `csa_values' in the directory `data', where spins are only identified by residue name and number, type one of the following:
relax> value.
[0]
[0]read(
[0]
[0]`CSA', `data/csa_value', spin_id=
[0]
[0]`@N')
relax> value.
[0]
[0]read(
[0]
[0]`CSA', `csa_value', dir=
[0]
[0]`data', spin_id=
[0]
[0]`@N')
relax> value.
[0]
[0]read(
[0]
[0]param=
[0]
[0]`CSA', file=
[0]
[0]`csa_value', dir=
[0]
[0]`data', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4, spin_id=
[0]
[0]`@N')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
Setting a parameter value may have no effect depending on which model-free model is chosen, for example if
values and
values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.
Note that the
values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:
/ (2.0 *
* frequency) ** 2
where:
is the chemical exchange value for the current frequency.
is in the namespace of relax, ie just type `pi'.
(see table 10.33)
In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.
(see table 10.34)
Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.
(see table 10.35)
Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle
of the third state is specified using the string `gamma2'.
(see table 10.36)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Set spin specific data values.
val: The value(s).
param: The parameter(s).
spin_id: The spin identifier.
If this function is used to change values of previously minimised results, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset to None.
The val argument can be None, a single value, or an array of values while the parameter argument can be None, a string, or array of strings. The choice of which combination determines the behaviour of this function. The following table describes what occurs in each instance. The Value column refers to the `val' argument while the Param column refers to the `param' argument. In these columns, `None' corresponds to None, `1' corresponds to either a single value or single string, and `n' corresponds to either an array of values or an array of strings.
(see table 10.37)
If the `spin_id' argument is left as the default of None, then the function will be applied to all spins. If the data is global non-spin specific data, such as diffusion tensor parameters, supplying the spin identifier will terminate the program with an error.
To set the parameter values for the current data pipe to the default values, for all spins, type:
relax> value.
[0]
[0]set(
[0]
[0])
To set the parameter values of residue 10, which is in the current model-free data pipe `m4' and has the parameters {
,
,
}, the following can be used.
term is the value for the first given field strength.
relax> value.
[0]
[0]set(
[0]
[0][0.97, 2.048*1e-9, 0.149], spin_id=
[0]
[0]`:10')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.97, 2.048*1e-9, 0.149], spin_id=
[0]
[0]`:10')
To set the CSA value of all spins to the default value, type:
relax> value.
[0]
[0]set(
[0]
[0]param=
[0]
[0]`csa')
To set the CSA value of all spins to -172 ppm, type:
relax> value.
[0]
[0]set(
[0]
[0]-172 * 1e-6, `csa')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]-172 * 1e-6, param=
[0]
[0]`csa')
To set the NH bond length of all spins to 1.02 Å, type:
relax> value.
[0]
[0]set(
[0]
[0]1.02 * 1e-10, `bond_length')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]1.02 * 1e-10, param=
[0]
[0]`r')
To set both the bond length and the CSA value to the default values, type:
relax> value.
[0]
[0]set(
[0]
[0]param=
[0]
[0][`bond length', `csa'])
To set both
and
to 100 ps, type:
relax> value.
[0]
[0]set(
[0]
[0]100e-12, [`tf', `ts'])
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]100e-12, param=
[0]
[0][`tf', `ts'])
To set the
and
parameter values of residue 126, Ca spins to 0.56 and 13 ps, type:
relax> value.
[0]
[0]set(
[0]
[0][0.56, 13e-12], [`S2', `te'], `:126@Ca')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.56, 13e-12], param=
[0]
[0][`S2', `te'], spin_id=
[0]
[0]`:126@Ca')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.56, 13e-12], param=
[0]
[0][`S2', `te'], spin_id=
[0]
[0]`:126@Ca')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
Setting a parameter value may have no effect depending on which model-free model is chosen, for example if
values and
values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.
Note that the
values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:
/ (2.0 *
* frequency) ** 2
where:
is the chemical exchange value for the current frequency.
is in the namespace of relax, ie just type `pi'.
(see table 10.38)
(see table 10.39)
In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.
(see table 10.40)
(see table 10.41)
If the diffusion tensor has not been setup, use the more powerful function `diffusion_tensor.init' to initialise the tensor parameters. This function cannot be used to initialise a diffusion tensor.
The units of the parameters are:
.
,
,
,
,
,
,
.
and
.
,
,
,
,
).
When setting a diffusion tensor parameter, the residue number has no effect. As the internal parameters of spherical diffusion are {tm}, spheroidal diffusion are {
,
,
,
}, and ellipsoidal diffusion are {
,
,
,
,
,
}, supplying geometric parameters must be done in the following way. If a single geometric parameter is supplied, it must be one of
,
,
,
, or
. For the parameters
,
,
,
, and
, it is not possible to determine how to use the currently set values together with the supplied value to calculate the new internal parameters. For spheroidal diffusion, when supplying multiple geometric parameters, the set must belong to one of
,
},
,
},
,
},
,
},
,
},
where either
,
, or both orientational parameters can be additionally supplied. For ellipsoidal diffusion, again when supplying multiple geometric parameters, the set must belong to one of
,
,
},
,
,
},
,
,
},
where any number of the orientational parameters,
,
, or
can be additionally supplied.
(see table 10.42)
(see table 10.43)
Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.
(see table 10.44)
These values are completely arbitrary as peak heights (or volumes) are extremely variable and the Rx value is a compensation for both the R
and R
values.
(see table 10.45)
Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle
of the third state is specified using the string `gamma2'.
(see table 10.46)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
(see table 10.47)
In this table, N is the total number of states and c is the index of a given state ranging from 0 to N-1. The default probabilities are all set to be equal whereas the angles are given a range of values so that no 2 states are equal at the start of optimisation.
Note that setting the probability for state N will do nothing as it is equal to one minus all the other probabilities.
Write spin specific data values to a file.
param: The parameter.
file: The name of the file.
dir: The directory name.
bc: A flag which if True will cause the back calculated values to be written to file rather than the actual data.
force: A flag which, if set to True, will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory.
The parameter argument should be a string.
To write the CSA values to the file `csa.txt', type one of:
relax> value.
[0]
[0]write(
[0]
[0]`CSA', `csa.
[0]
[0]txt')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`CSA', file=
[0]
[0]`csa.
[0]
[0]txt')
To write the NOE values to the file `noe', type one of:
relax> value.
[0]
[0]write(
[0]
[0]`noe', `noe.
[0]
[0]out')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out', force=
[0]
[0]True)
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.48)
(see table 10.49)
(see table 10.50)
(see table 10.51)
(see table 10.52)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Function for viewing the collection of molecules extracted from the PDB file.
relax> vmd.
[0]
[0]view(
[0]
[0])
Edward d'Auvergne 2011-08-12